Troubleshooting

Most issues have a quick fix. Search this page for your symptom; if you don't find it, open an issue on GitHub.

Hotkey doesn't fire

Causes, in order of likelihood:

  1. Another app claimed the same shortcut. Check System Settings → Keyboard → Keyboard Shortcuts for conflicts. Spotlight, Raycast, and macOS dictation are common culprits.
  2. Input Monitoring not granted. Modifier-only hotkeys (like Right Option) need it. Grant in System Settings → Privacy & Security → Input Monitoring.
  3. Accessibility permission revoked. Re-grant in System Settings → Privacy & Security → Accessibility.
  4. The hotkey field didn't capture properly. Re-record it in Settings → Hotkeys.

Recording works but text doesn't paste

Almost always Accessibility permission. Open System Settings → Privacy & Security → Accessibility, ensure Neuron Flame is listed and toggled on. If it's listed but still failing:

  1. Toggle it off, then on.
  2. Quit and reopen Neuron Flame.

If it's still failing:

tccutil reset Accessibility com.neuronflame.app

Then quit, reopen, and re-grant when prompted.

Permissions reset after every rebuild

Symptom: you build the app from source, and macOS forgets all your permissions every time.

Cause: ad-hoc code signing (the default for free local builds) generates a new signature every build, and macOS treats each one as a different app.

Fix: Neuron Flame's make local uses a stable self-signed certificate called Ziva AI Developer in your login Keychain. The cert is created once and re-used forever, so permissions stick across rebuilds. If you've blown away your login Keychain or the cert was deleted, the Makefile will recreate it on the next build.

If you accidentally have a different cert in LocalBuild.xcconfig, fix it back to Ziva AI Developer and rebuild.

Audio appears empty / silent transcripts

Causes:

  1. Wrong input device. macOS sometimes routes audio to a Bluetooth device or a virtual mic. Open System Settings → Sound → Input and confirm your physical mic is selected.
  2. Mic permission denied. System Settings → Privacy & Security → Microphone, toggle Neuron Flame on.
  3. Mic gain too low. Speak directly into the mic; check the input level in System Settings → Sound → Input while speaking.

Model download stuck or corrupted

Symptoms: progress bar at 0% or 99%, transcription says "model failed to load".

  1. Click Cancel on the model row.
  2. Quit Neuron Flame.
  3. Run: 
    rm -rf ~/Library/Application\ Support/com.neuronflame.app/Models/[model-name]/
  4. Reopen and click Download again.

App won't open: "damaged" or "from an unidentified developer"

You're running an old, pre-notarisation download. Neuron Flame is now Apple-notarised — grab a fresh DMG from neuronflame.com/downloads/Neuron%20Flame.dmg and replace the installed copy. The new build opens with a normal double-click.

If you really want to run the old self-signed build for some reason:

  1. Open System Settings → Privacy & Security.
  2. Scroll to the bottom — you'll see "Neuron Flame was blocked from use".
  3. Click Open Anyway.

Sparkle update fails

Sparkle requires the new build's signature to match the EdDSA public key embedded in the running build. If you're running a hand-compiled build, Sparkle will refuse signed-by-someone-else updates as a security measure.

To get back on the official update channel: download a fresh DMG from GitHub Releases and replace your installed copy.

App opens then crashes immediately

Almost always a corrupted SwiftData store from an interrupted upgrade. Move (don't delete — keep a backup) the Application Support folder:

mv ~/Library/Application\ Support/com.neuronflame.app ~/Desktop/com.neuronflame.app.broken

Reopen Neuron Flame. It will start fresh.

To recover transcripts from the moved folder, look in com.neuronflame.app.broken/default.store — that's the SwiftData file. If you want help recovering it, attach it to a GitHub issue (it doesn't contain audio, just transcribed text + metadata).

AI Enhancement returns errors / nothing

If the LLM call fails for any reason — rate limit, expired key, network issue — Neuron Flame falls back to the raw transcript automatically. You always get something pasted; you never get an error string in your document.

To see what went wrong, open the History tab → click the failed entry. If it's a configuration issue, the AI Models tab will show the error inline.

I'm getting stray <TRANSCRIPT> tags in my output

Neuron Flame strips the wrapper artifacts (<TRANSCRIPT>, <CLIPBOARD_CONTEXT>, etc.) from LLM responses automatically. If you see them anyway, you're on an older build — update to latest.

Still stuck?

Open an issue on GitHub with: