Troubleshooting

"Unknown developer" / can't open the app

The app isn't code-signed yet, so each OS warns you once. This is expected — follow the per-platform steps on the install page:

• macOS: right-click the app → Open → Open. Or clear quarantine: xattr -dr com.apple.quarantine "/Applications/Chronicle Keeper.app"
• Windows: SmartScreen → More info → Run anyway.

Blank or black window on Linux

This is a known WebKitGTK rendering quirk. Chronicle Keeper already applies the standard fix (forces the X11 backend and disables DMABUF) unless you've set those variables yourself. If you still see a blank window, try launching with them explicitly:

GDK_BACKEND=x11 WEBKIT_DISABLE_DMABUF_RENDERER=1 ./Chronicle*.AppImage

Transcription model won't download

On first transcription the Parakeet speech model downloads once (a few hundred MB). If it fails:

• Check your internet connection and that nothing is blocking the download.
• Make sure you have enough free disk space in your app-data folder.
• Try again — the download resumes/retries. Once it's cached, you're offline-capable.

Transcription is slow

Transcription runs on CPU and scales with your processor. A few pointers:

• It's normal for a multi-hour session to take a while — still a fraction of real time on most machines.
• If your build supports it, the transcription_accelerator setting (coreml / cuda / directml) can use hardware acceleration; it falls back to CPU automatically if the runtime doesn't support your choice.
• Close other heavy apps so the transcoder gets the cores.

LLM test fails / no summary

If the Test button in Settings is red, or summaries error out:

• Ollama: confirm it's running (ollama serve) and reachable at http://localhost:11434, and that you've ollama pull-ed the model you selected.
• Cloud key: double-check the key was pasted in full with no stray spaces, that billing/credit is set up, and that the model name is one your account can access.
• Wrong provider selected: make sure the provider in Settings matches the key you pasted.
• See the LLM setup guide for the exact steps per provider.

Summary errors with "request failed" or times out (local)

A local model summarizing a long session can take several minutes. If it gives up partway:

• This is usually a timeout, not a real failure — the model was still working. Raise ollama_timeout_seconds in Settings and try again.
• Check ollama ps in a terminal while it runs. 100% GPU is good; if it shows % CPU, the model spilled out of memory and will be very slow — use a smaller model or lower the context cap.
• Cloud providers avoid this entirely if you need a fast result.

Summary is vague or generic (local)

If a local summary reads like it only skimmed the session — generic statements, missing the second half, wrong or missing names — the model likely wasn't seeing the whole transcript. Update to the latest version: Chronicle Keeper now sizes the context window to your full session automatically. Older builds silently truncated long transcripts. A larger model (e.g. gemma4:e4b) also captures more detail than a tiny one.

Getting detailed logs

Building or running from source? Launch the core with verbose logging to see what's happening:

RUST_LOG=debug cargo run -p ck-core --bin ck-serve

Still stuck?

Open an issue with what you tried and any error text — github.com/aronjanosch/chronicle-keeper/issues.