Skip to main content

Troubleshooting

The AI isn't responding​

Check your provider is configured. Open Settings → AI Providers and make sure the provider you're using shows as connected. If it shows an error, try reconnecting.

Check your API key. If you're using a raw API provider (Anthropic, OpenAI, etc.), your key might have expired or run out of credits.

For Claude Code or Codex: The CLI session might have expired. Go to Settings → AI Providers and reconnect. For Claude Code, this opens a terminal window and you re-authenticate via browser.

Try Reindex All. Go to Settings → AI Providers → Embeddings and click Reindex All. This rebuilds the search index from scratch.

Check the notes folder. Settings → General shows the path. Make sure it's pointing to the right folder.

Keep notes in the main notes folder if something looks off. Coeus watches the notes directory for changes, but the most reliable setup is to keep your .md notes at the top level of the folder you selected in Settings.

Semantic search isn't working​

Check your embeddings configuration. Settings → AI Providers → Embeddings. Make sure the API URL, model, and dimensions are all correct.

Click Fill Missing. This backfills embeddings for notes that do not have them yet. It is useful after changing embedding settings or importing a large batch of notes.

Recent notes should usually update automatically. If embeddings are configured, Coeus tries to fill missing embeddings in the background after notes change. Use Fill Missing when you want to catch up everything manually.

Test the endpoint. If you're using Ollama, make sure it's running (ollama serve) and that the model is pulled (ollama pull nomic-embed-text).

Telegram bot isn't responding​

Check the bot is enabled. Open Settings → Integrations and make sure Enable private Telegram DM bridge is turned on.

Make sure a Coeus runtime is running. Telegram works when either the desktop app is running or coeus-headless run is running.

Check vault ownership conflicts. Coeus now enforces a single-owner vault lock. If desktop and headless try to run at the same time against the same vault, one process will refuse to start.

Avoid keychain prompts in unattended mode. On macOS, a locked keychain can block headless Telegram startup. For non-interactive runs, set COEUS_TELEGRAM_BOT_TOKEN in the runtime environment so Coeus can start without keychain unlock UI.

Use universal encrypted secrets when needed. Set COEUS_SECRET_BACKEND=age and provide COEUS_SECRETS_PASSPHRASE so desktop/CLI/headless share one encrypted secrets file without relying on keychain unlock state. Optionally set COEUS_SECRETS_FILE to control the file path.

Re-link if needed. If you got a new phone or Telegram account, generate a new link code and send /link CODE to the bot again.

Audio transcription is slow​

Local Whisper transcription speed depends on the model and your hardware. The tiny.en model is fastest; medium.en is slowest. On an Apple Silicon Mac, even medium.en is reasonably quick. On older hardware, stick to base.en or tiny.en.

For faster transcription, switch to OpenAI API in Settings → Integrations → Speech & Transcription.

A note has a conflict (Reload vs. Keep my edits)​

This happens when the note file changed on disk while you were editing it in Coeus: usually because a sync tool (Dropbox, iCloud) updated it, or because you were editing it in another app at the same time.

  • Reload: Discard your edits and load the version from disk
  • Keep my edits: Save your current edits, overwriting the disk version

If you're not sure which version has the content you want, open the file in a text editor to check before deciding.

Something else is wrong​

Reach out through usecoeus.com. Include your OS version and what you were doing when it happened.