Troubleshooting

Common symptoms and how to fix them. If your issue isn’t here, check the FAQ or open a thread in Discussions.

Startup fails

ModuleNotFoundError: No module named 'src'

You’re trying to invoke Cogtrix without uv or the venv isn’t activated. Use uv run python cogtrix.py from the repo root, never python cogtrix.py directly.

COGTRIX_JWT_SECRET must be set to at least 32 characters

API mode requires the JWT secret. Generate one:

export COGTRIX_JWT_SECRET="$(python -c 'import secrets; print(secrets.token_hex(32))')"

For a persistent setup, write it to your shell rc or use docker’s -e flag.

Configuration error on first run

Run the setup wizard:

uv run python cogtrix.py --setup

It writes a starter ~/.cogtrix.yml you can edit.

Provider problems

Failed to connect to Ollama at localhost:11434

Ollama isn’t running. Start it:

ollama serve   # in another terminal

Or, if you don’t have Ollama installed, set up a cloud provider with an API key — see Installation.

Model 'qwen3:8b' not found

Pull it:

ollama pull qwen3:8b

Any GGUF model works. Run ollama list to see what you have locally.

401 Unauthorized from OpenAI / Anthropic / etc.

API key is unset or invalid. Verify with:

echo $OPENAI_API_KEY

If it’s there and you’re still getting 401, the key may have been revoked or rate-limited.

Cogtrix uses the wrong model

Three places set the model, in priority order:

1. --model / -m CLI flag (highest)
2. default_model in config
3. Auto-detected from the first available provider (lowest)

Run uv run python cogtrix.py --check-config to see which resolved.

Tool problems

Tool keeps asking for confirmation

That’s the safety system — see Tool safety. Press a at the prompt to auto-approve for the rest of the session, or pass -y on startup to auto-approve everything.

Permission denied writing a file

The agent’s file tools are sandboxed if you started Cogtrix with --allow-write-path. Either:

• Remove --allow-write-path (no sandbox)
• Add the target directory: --allow-write-path /your/dir --allow-write-path /another

MCP server didn’t load any tools

Check the server’s status:

/mcp

If it shows disconnected, the subprocess failed to start. Run cogtrix --debug and look for the spawn error — usually it’s a missing executable or wrong arguments.

Memory and sessions

Conversation context is wrong / stale

Either:

• Different session ID. Cogtrix loads history by session — -s default is the default. Pass -s <name> to switch.
• Memory mode mismatch. /mode shows the current mode; /mode <name> switches.
• Compression triggered. /compact and the auto-compression at 75% context utilisation summarise older messages.

To wipe a session: /clear (interactive) or delete data/history/<session-id>.json.

Token limit exceeded from the LLM

Cogtrix tries to keep context within context_window from your config. If you’re seeing this from the model:

1. Confirm context_window matches the model’s actual capacity (e.g. 8192 for Llama-2, 128000 for GPT-4-turbo).
2. Try /compact to summarise old turns.
3. Lower working_memory_size in config to evict more aggressively.

API / WebSocket

WebSocket closes immediately with code 4001

Authentication failure. Either the JWT is missing or the token doesn’t match the server’s COGTRIX_JWT_SECRET. Re-login via POST /auth/login, then re-open the WebSocket.

429 Too Many Requests from the API

Per-user rate limiting. See Rate limiting for the default quotas and how to raise them in config.

503 Service Unavailable from /api/v1/sessions/...

The in-memory session registry hasn’t initialised. Usually means the backend is still warming up after a restart. Wait ~5 seconds and retry.

Performance

Slow on a CPU-only machine

• Use a smaller model — qwen3:4b instead of qwen3:8b.
• Avoid /think and /delegate (both spawn extra LLM calls).
• Set auto_route_fast_model so simple queries skip the heavy model.

High memory usage

• Vector DB cache. Clear with rm -rf data/vectordb/cache/.
• Long conversation history. /clear or /compact.
• Multiple sessions kept warm. Restart the API server to drop them.