Troubleshooting

Common issues and how to resolve them.

Dictation Issues

Dictation doesn't start when I press the hotkey

1. Check hotkey configuration -- go to Settings > Input > Hotkey shortcuts and verify your dictation hotkey is set
2. Check microphone permissions -- your OS may be blocking microphone access. On Windows, check Settings > Privacy > Microphone. On Linux, check PulseAudio/PipeWire permissions
3. Check the microphone selection -- go to Settings > Input and verify the correct input device is selected
4. Test the microphone -- use the microphone test button in Settings to confirm audio is being captured
5. Restart Conjure -- hotkey registration can occasionally fail on startup. A restart resolves it

Dictation records but no text appears

1. Check transcription provider -- verify you have a provider configured (local whisper or a cloud API key)
2. Test your API key -- go to Settings > API Keys and click Test on your transcription key
3. Check internet connection -- cloud providers require internet access. Local whisper works offline
4. Check the whisper model -- if using local whisper, ensure a model has been downloaded. The first transcription triggers a download
5. Look at the pill overlay -- if it stays on "processing" (blue), the transcription is taking a long time or has stalled

TIP

Most transcription accuracy issues can be resolved by switching to a cloud provider (Groq is free) or adding frequently misrecognized words to your dictionary.

Transcription is garbled or inaccurate

1. Adjust audio preprocessing -- go to Settings > Input > Audio and try:
   • Lowering the noise gate threshold if words are being cut off
   • Enabling the high-pass filter to remove background rumble
   • Enabling normalization for consistent volume
2. Try a larger whisper model -- if using local whisper, larger models (large-v3) are more accurate than smaller ones
3. Switch providers -- cloud providers (Groq, Deepgram) often produce better results than local whisper
4. Add dictionary entries -- add frequently misrecognized words to your glossary
5. Check your microphone -- a dedicated mic positioned 6-12 inches from your mouth produces much better results than a laptop mic

Whisper hallucinates text from silence

This is a known whisper behavior where it generates phrases like "Thank you for watching" or "Subscribe" when processing silent audio.

1. Increase noise gate threshold -- set it to 0.02-0.05 in Settings > Input > Audio
2. Conjure's tuned parameters help -- the no-speech threshold is set to 0.4 (more aggressive silence detection than the default 0.6)
3. Speak promptly -- avoid long pauses at the start or end of your recording

Text is pasted in the wrong application

Conjure pastes into the application that was focused when you released the dictation hotkey. If you switch apps during recording, the text goes to whatever is focused at paste time.

• Keep your target app focused while dictating
• In streaming mode, text is injected continuously into whatever is focused at each moment

Agent Mode Issues

Agent can't run terminal commands

1. Check tool permissions -- if you haven't enabled "Dangerously skip permissions," you need to approve each tool invocation
2. Check the command -- the agent runs commands in your user context. Commands requiring admin/sudo won't work without elevation
3. Verify provider -- agent mode requires an LLM provider configured (not just a transcription provider)

Agent responses are poor quality

1. Use a capable model -- GPT-4o, Claude, or similar. Smaller models may struggle with tool use
2. Be specific -- "paste hello world" is clearer than "write something"
3. Check context -- start a new conversation if the agent seems confused by old context

Screenshots aren't working

1. Use a vision-capable model -- GPT-4o or Claude with vision support
2. Screen capture permissions -- on some platforms, screen capture requires explicit permission
3. Check agent output -- the agent may have captured the screenshot but the model can't interpret it (non-vision models return an error)

Text-to-Speech Issues

TTS hotkey doesn't speak text

1. Select text first -- you must have text highlighted before pressing the TTS hotkey
2. Check hotkey configuration -- verify the "Speak selected text" hotkey is set in Settings
3. Check TTS provider -- ensure a TTS provider is configured in Settings > Processing > Text-to-Speech
4. Check toast messages -- Conjure shows a toast if it can't read the selection or TTS fails
5. Try clipboard fallback -- if the accessibility API can't read the selection, Conjure tries copying via Ctrl+C. Some apps may block this

TTS sounds robotic

• Switch to OpenAI TTS or Edge TTS for higher-quality neural voices
• System voices vary significantly by platform and installed voice packs

Application Issues

App won't start

1. Check for migration errors -- if the SQLite database is corrupted or a migration fails, the app may not start
2. Delete the database -- find conjure.db in your app data directory and delete it. You'll lose settings and history but the app will start fresh

Destructive action

Deleting conjure.db permanently erases all settings, transcription history, dictionary entries, API keys, and conversation data. Back up the file first if you want to preserve any data.

3. Check logs -- Tauri logs are in your system's app log directory

App crashes during recording

1. Check available memory -- whisper models (especially large-v3) require significant RAM
2. Try CPU mode -- if GPU transcription crashes, switch to CPU mode in Settings
3. Update GPU drivers -- Vulkan GPU transcription requires up-to-date GPU drivers

Settings keep reverting

1. Check for database write errors -- if SQLite can't write, preferences won't persist
2. Don't run multiple instances -- two Conjure instances writing to the same database causes conflicts
3. Check disk space -- SQLite needs space to write journal files

Performance Issues

Transcription is slow

1. Use GPU mode -- if you have a supported GPU (Vulkan on Windows/Linux, Metal on macOS), enable GPU transcription for 5-10x speed improvement
2. Use a smaller model -- smaller whisper models transcribe faster but with lower accuracy
3. Use a cloud provider -- Groq and Deepgram return results in 1-3 seconds regardless of audio length
4. Check audio length -- very long recordings (>60s) take proportionally longer to process

High CPU usage

1. Whisper is CPU-intensive -- during local transcription, expect high CPU usage. It returns to normal after processing
2. GPU offloading -- enable GPU mode to shift the workload from CPU to GPU
3. Background processing -- the sidecar process runs idle between transcriptions and shouldn't use significant CPU

Still Stuck?

• Check the FAQ for answers to common questions
• Search GitHub Issues for known bugs
• File a new issue with your OS version, Conjure version, and steps to reproduce

Getting Help

If your issue isn't covered here:

• GitHub Issues -- report bugs or request features
• GitHub Discussions -- ask questions, share tips, discuss ideas
• Documentation -- full guides for every feature