Troubleshooting
Start with kaja doctor (local mode). It tests every key, model, MCP server and tool, asks for what’s missing, and ends with what’s still broken. kaja config paths shows which files Kaja actually reads.
Common problems
The model doesn’t answer. Run kaja doctor. It tries every model, and if the one a task uses fails but another configured for that task works, it offers to switch. For a local server, check it’s running at the base_url in models.toml.
“No chat model” in local mode. Local mode needs a model in models.toml that lists chat in its tasks, and never falls back to cloud. Add one, run kaja config wizard, or start with kaja --cloud.
Cloud mode won’t sign in: keychain unavailable. The token is only kept in the OS keychain, with no plaintext fallback. Use kaja --local, or unlock or install a keychain (on Linux, a Secret Service provider such as GNOME Keyring or KWallet).
kaja abilities update fails. It needs git 2.25 or newer, and kaja doctor shows the version it found. A private or mistyped [marketplace] url fails instead of asking for a password. Also check that [marketplace] enabled isn’t false.
An ability doesn’t show up. A chat only gets the abilities its persona lists in abilities (see Personas); kaja abilities shows which personas use each one. One that needs a key stays out until the key is in secrets.toml (kaja doctor asks for it). kaja doctor lists everything left out and why.
An MCP server’s tools are missing. A server that fails to connect, or takes over 10 seconds, is skipped so the session can still start. Check its command or URL, and its secrets.
Alt shortcuts type strange characters (macOS). Set hotkeyModifier = "ctrl" in settings.toml, or turn on “Option as Meta” in your terminal.
A setting change did nothing. Config is read once at startup, so restart Kaja. The local Telegram bot needs a restart too.
Logs
The terminal UI never logs to the screen. For a log file, set both variables:
KAJA_LOG_LEVEL=debug KAJA_LOG_FILE=~/kaja.log kaja
Levels are trace, debug, info, warn, error and fatal. The file is JSON lines and includes the agent’s warnings: skipped abilities, missing keys, failed MCP connections.
Still stuck?
Open an issue on GitHub with the kaja doctor output. Every config file except secrets.toml is safe to include.
Next: