Troubleshooting

Configuration validation failed: Missing critical environment variable: ANTHROPIC_API_KEY must be provided

Anthropic is the only supported LLM provider. Set ANTHROPIC_API_KEY in your .env file or environment, then restart the process (see Configuration).

Configuration validation failed: Missing critical environment variable: PATBA_API_KEY ...

Set PATBA_API_KEY (or API_KEY / AWS_APP_API_KEY) in your .env file or environment. This key is required to authenticate REST API requests and by the ACP/CLI entrypoints' shared validation path.

REST requests return 401 Unauthorized

Every route except / and /health requires an X-API-Key HTTP header equal to your configured PATBA_API_KEY. Double-check the header name (X-API-Key, case-insensitive) and value.

No Anthropic API key provided. Please set ANTHROPIC_API_KEY to use the agent.

Thrown by createChatModel() in src/utils/model.ts when the agent is built but no Anthropic key is configured. There is no fallback provider — set ANTHROPIC_API_KEY.

400 ... \temperature` is deprecated for this model`

Claude Sonnet 5 rejects the temperature parameter, so createChatModel() does not send one. If you reintroduce it, expect this error.

SLACK_BOT_TOKEN is not set. Slack integration is disabled.

This is an informational log message, not an error. The /webhooks/slack endpoint will still receive events, but cannot post responses back to Slack until SLACK_BOT_TOKEN is configured.

Local runs silently use an in-memory (non-persistent) S3 store

If AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY and every other source in the AWS SDK's default credential chain (shared config, SSO/AWS_PROFILE, container/instance roles) resolve to nothing, src/storage/s3.ts logs a warning and falls back to an in-memory mock store that does not persist across process restarts. This is expected for local development; local SQLite checkpoints are unaffected. It is also currently true of the deployed service: the Lightsail container service is not given any IAM role for runtime AWS access (see Infrastructure), so production runs on the mock store too until that is wired up.

The agent keeps steering me back to its topic menu

The Brain only teaches and writes from its own knowledge store, and it will not invent material outside it. If your request falls outside the four topics (see the FAQ), it will say so and offer the menu again. Pick a topic, then a subtopic, and it will proceed.

The agent says it found no material for a subtopic

Retrieval searches src/storage/knowledge-store.json with BM25, fused with vector similarity when embeddings are available, so it tolerates paraphrase far better than it used to — but the store only covers four areas, and nothing outside them exists to find. Rephrase using terms closer to the stored material (e.g. "Conway", "IELTS", "EC2"). If the store is missing or empty, run npm run ingest to regenerate it.

If answers seem to miss the point of a question, check whether embeddings were built: the startup log reports Loaded N vectors when they were, and retrieval silently falls back to BM25 alone when they were not. See Retrieval.

npm run mcp / npm run start prints unexpected extra text on stdout

Both the MCP server and the raw ACP server rely on stdout being reserved exclusively for protocol JSON-RPC traffic. Progress logs are intentionally routed to stderr - make sure any custom logging additions follow the same convention, or downstream clients may fail to parse responses.

Build fails or entrypoints can't find compiled files

Run npm run build before using any npm run <entrypoint> script (start, cli, server, mcp) - they all execute compiled output from dist/, not the TypeScript sources directly.