Reference
Troubleshooting
Uses the Ahena CLI (beta). Install it with npm install -g @ahena/cli, or prefix commands with npx @ahena/cli. See Installation. The dashboard covers projects, connections, Doctor, the Stack Graph, plans and approvals without it.
| Message | What to do |
|---|---|
| "You're not signed in." | ahena login. In CI, set AHENA_TOKEN (ahena ci token create). |
| "You're signed in to X, not Y." | --api-url / AHENA_API_URL points elsewhere; sign in to that API. |
| "Project … wasn't found, or you don't have access to it." | Check organization/project in ahena.config.ts, or ask an admin to add you. |
| "ahena.config.ts needs Node.js 22.18 or newer." | Upgrade Node (the config file is loaded with Node's type stripping). |
| "Secrets must not be stored in ahena.config.ts." | Move the value to ahena env set. |
A provider "isn't connected yet" after connect |
The provider accepted the key but needs attention (e.g. a test key in production); the message says what. |
| "… tried to reach …, which isn't one of its declared hosts." | A provider attempted an undeclared request and Ahena blocked it. Report it. |
| Doctor: webhook endpoint FAIL | Your route is missing, or accepts unsigned requests. ahena generate writes a verifying route. |
| Doctor: migrations not applied | Apply supabase/migrations with supabase db push. |
generate says "kept your edits" |
You changed a generated file; Ahena kept it. --force replaces it. |
ahena drift reports changes you made on purpose |
Accept them (ahena drift --accept), and update ahena.config.ts if it declares those values. |
deploy-check: "Can't read … with this token." |
The CI token was revoked, expired, or belongs to another project. |
| CI token gets 403 | CI tokens only read and run checks. Use a person's session for changes. |
| Ollama "isn't reachable" | ollama serve, and check OLLAMA_HOST. Ahena checks it from your machine only. |
| MCP: "read-only" | Restart with ahena mcp --allow-write if you want the agent to make changes. |
| MCP: "needs the developer's approval" | Your client can't show approval prompts; run the suggested ahena configure yourself. |
Still stuck? ahena doctor --json and the request id from an error message (x-request-id)
help trace a problem in the activity log.