Run habakkuk doctor first. It checks the config, every provider's keys, the databases, each channel's credentials, the HTTP section and MCP servers, prints one line per item, and exits non-zero when something is wrong. Then habakkuk channels for live channel health and habakkuk logs -f -level warn for what serve is doing.

Each channel page also has a troubleshooting table: WhatsApp, Telegram, Slack, Discord, Signal, Matrix.

Setup and config#

You see	Cause and fix
no config at ~/.habakkuk/config.yaml yet: run `habakkuk setup`	No config yet. Run `habakkuk setup` (or `habakkuk init` to write a starter file by hand). If you have one elsewhere, set `HABAKKUK_HOME`.
`config: UNKNOWN KEY "modle" in Agent (line 12) (ignored; ...)`	A typo, or a setting from a newer release. Fix the spelling; the key is ignored until then.
`agent habakkuk: unknown provider "x" in "x/model"`	The part before `/` in `model` must be a name under `providers:`.
`model "x": want <provider>/<model>`	Write models as `provider/model-id`.
`agent habakkuk: routing "auto" needs a fast_model`	Add a `fast_model`, or remove `routing`.
`agent habakkuk: toolset "mcp:x" names no configured MCP server`	Add the server under `mcp_servers:`, or fix the name.
`channel telegram: token_env is required for telegram`	Each channel type has required settings; see its page.
`channel x: agent "y" is not configured`	The channel's `agent` (or a route) names an agent that does not exist.
`transcription: provider "x" must be a configured provider of type openai`	Point `transcription.provider` at a provider with `type: openai` (or an OpenAI-compatible preset).
`version N is not supported (want M)`	The config was written for a newer release. Update Habakkuk, or put back the config that came with this one (`habakkuk update --rollback` restores it).
A hand edit to `config.yaml` seems ignored	`serve` logs `config.yaml changed; restart habakkuk serve to apply` for most sections, and `config.yaml changed but does not load; still running the previous config` when the file is invalid. Fix it, then restart `serve`.

Keys and providers#

You see	Cause and fix
`provider anthropic: 0/1 keys present` in `habakkuk doctor`	The variable in `keys_env` is not set. Put it in `$HABAKKUK_HOME/.env` (not in `config.yaml`).
`provider chatgpt: NOT LOGGED IN (run habakkuk auth login chatgpt)`	Run the command it names.
Turns fail with an auth or billing error	The key is wrong, revoked or out of credit. With several keys in `keys_env`, Habakkuk rotates to the next one; with `fallbacks`, it tries the next model.
`mcp x: MISSING ...` or `not signed in; run habakkuk mcp login x`	Set the variable the server needs, or sign in.

Channels#

Symptom	Cause and fix
The bot answers with a pairing code	You are not in `allow_from`. Run `habakkuk pair CODE` on the server (the code works for one hour).
The bot ignores group messages	By default it answers only when mentioned or replied to (`groups: mention`). Set `groups: all` to answer everything.
Nothing happens, and another `habakkuk serve` is running	Only one program may poll a channel. Stop the other one; run one `serve` per `$HABAKKUK_HOME`.
A webhook channel (SMS, Teams, Google Chat...) receives nothing	The platform must reach `<public_url>/channels/<name>`. Check `public_url`, the proxy or tunnel, and the URL `habakkuk doctor` prints. Tailscale addresses are private, so platforms cannot reach them.
A channel shows as down in `habakkuk channels`	It is being restarted with backoff. Its last error is shown; errors marked fatal (a bad token) stop it until you fix the config and restart `serve`.
Voice notes are not understood	Configure `transcription:`. Without it, the agent is told it cannot hear the note.
`This chat can't receive files.` on `/export`	The platform has no file sending in Habakkuk (for example IRC or Twitch). Use `habakkuk sessions export ID`.

Approvals and permissions#

You see	Cause and fix
`No answer, so I skipped that step.`	An approval waited 15 minutes. Answer yes or no sooner, or use an approval reviewer for routine steps.
`... needs approval and no one is attending this run`	A schedule, sub-agent, webhook or API call needed approval. Give the agent `approvals: reviewer` or `reviewer_then_human`, or a wider `permission`.
`... is not allowed in read-only mode`	The agent is `permission: read-only`, which also denies network tools such as the browser. Use `workspace`.
`... is not available to messages from people other than the owner`	The sender is a guest (let in by `allow_from: ["*"]`). Add their id to `allow_from` or pair them.
Commands need approval even in `full` mode	Turns from chat apps and turns that read outside content always need approval for risky calls. Set `trust: full` on the agent to treat your own chat messages like the CLI. See Security.

Budgets#

You see	Cause and fix
`Paused: the daily budget of $5.00 for agent habakkuk is used up; it resets at 00:00 ...`	A spending limit was reached. Raise it in `config.yaml` (it applies within seconds) or wait for the reset.
`Paused: x has no known price and budget.unknown_price is block`	Add the model under `pricing:`, or set `unknown_price: allow`.

Updates and databases#

You see	Cause and fix
`control.db has schema version N, but this habakkuk only knows up to version M`	A newer Habakkuk already upgraded the database. Run `habakkuk update`, or restore with `habakkuk update --rollback`.
`habakkuk update` stops after the upgrade check	The new release cannot run on your home as it is; nothing was changed. Read the message, or pass `-skip-upgrade-check` only if you are sure.
Something broke after an update	Stop `serve` and run `habakkuk update --rollback`.

HTTP server, dashboard and desktop app#

You see	Cause and fix
`http: listen 0.0.0.0:8484 is not a loopback address; set token_env so the API needs a token`	Set `http.token_env`, or listen on `127.0.0.1`.
`a channel of type web needs the http section`	Add an `http` section.
`no http section in config.yaml` from `habakkuk expose`, or the desktop app says `config.yaml has no http section`	Add `http: {listen: 127.0.0.1:8484, token_env: HABAKKUK_HTTP_TOKEN}` and put the token in `.env`.
`http.token_env is not set: give the API a token before sharing it on the tailnet`	Set `token_env` first.
Live mode cannot use the microphone	The page needs `localhost` or HTTPS. Use `habakkuk expose tailscale` or a reverse proxy with HTTPS.

Tools#

You see	Cause and fix
`computer use is not supported on Windows yet`	Use the browser tools, or run Habakkuk in WSL.
The browser does not start on a server	Install Chromium (`apt install chromium` on Debian), or set `browser.path`. In Docker, build the image with `--target browser`.
`duckduckgo refused the automated search`	Configure a search provider with a key (Brave, Tavily, Exa) or your own SearXNG.
Checkpoints are missing	`git` must be on `PATH`, and snapshots larger than `checkpoint_max_mb` are skipped.
`background services are set up for Linux (systemd) and macOS (launchd)`	`habakkuk setup service` does not cover your OS; run `habakkuk serve` with your own service manager.