Troubleshooting

Server-side problems are answered on this page; client-side ones live next to the integration they belong to — the table routes you.

By symptom

Symptom	Where to look
Install fails, container won't start, health check red, not running after a reboot	Install & server below
MCP tools never appear in Claude Code / every tool 401s	Claude Code integration → Troubleshooting
Claude Desktop connector won't attach	Claude Desktop connectors → Troubleshooting
Windows IDE can't reach the server, GPU not usable in Docker Desktop	Windows → Snags & fixes
Antigravity on Windows can't reach the WSL2 server	Antigravity on Windows → Troubleshooting
AnythingLLM can't see the server	AnythingLLM → Troubleshooting
Search returns nothing / results look stale	Index & search below — check index freshness first, then reindex
GPU not detected or out of memory	GPU compatibility matrix
Update didn't apply / version looks wrong	Updating CodeNavi

First moves, always

1. Health check: curl http://localhost:8765/health — version, GPU, index counts in one call.
2. Web UI System screen: http://localhost:8765/ui — the same data, plus per-codebase index state.
3. Freshness: zero or stale-looking search results usually mean the index is behind the working tree — run an incremental reindex (seconds) before anything else.

Still stuck? Email [email protected] with your /health output and what you tried.

Install & server

Container starts but health returns degraded: The model is still loading. Wait 1-2 minutes and retry. Check logs: docker compose logs -f codenavi

Windows: container restarts forever, log says Cannot write to /app/data (owned by uid=0): The installer's volume-preparation step did not finish, so the named volumes still belong to root. Installs made with a 1.3.36–1.3.41 package hit this on every fresh install; a 1.3.42 or later package is fixed. Re-run setup.ps1 from a current package over the same folder (Set-Location <install dir>; .\setup.ps1) — it re-seeds the volumes and keeps the licence, index and settings. Updates never cause this: update.ps1 does not touch the volumes.

CodeNavi is not running after a reboot (Docker): Check docker ps -a --filter name=codenavi. If STATUS reads Created (not Up, not Exited), Docker tried to bring the container back before its network bridge had an address, the host.docker.internal entry in the compose file could not be resolved, and the start was abandoned. The restart: unless-stopped policy does not retry this case — it only covers a container that ran and then exited. Confirm with docker inspect codenavi --format '{{.State.Error}}'; the message ends in host containers internal IP address is empty. It is a timing race, so it does not happen on every reboot.

Fix now: cd <install dir> && docker compose up -d. Health is back within two minutes.

Make it self-healing: a systemd unit that runs docker compose up -d after the network is up and retries until it succeeds. As the account that owns the install (needs loginctl enable-linger $USER once so the unit runs without a login):

# ~/.config/systemd/user/codenavi.service
[Unit]
Description=CodeNavi (docker compose up -d, retried until it sticks)
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=0

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/path/to/your/codenavi-install
ExecStartPre=/bin/sh -c 'for i in $(seq 1 60); do docker info >/dev/null 2>&1 && exit 0; sleep 2; done; exit 1'
ExecStart=/usr/bin/docker compose up -d
Restart=on-failure
RestartSec=15

[Install]
WantedBy=default.target

Then systemctl --user daemon-reload && systemctl --user enable --now codenavi.service. Set WorkingDirectory to the folder holding your docker-compose.yml and .env; if docker is not at /usr/bin/docker, use which docker. Podman installs have their own boot recipe: Podman → Keep it running after you log out.

Out of memory (OOM killed): The server needs ~8 GB RAM. Check dmesg | grep -i oom. Increase Docker memory limit or reduce concurrent usage (max 1 active session recommended).

Reindex finds 0 files, or says "Indexing REFUSED — codebase root … is empty / stale bind mount": Check that CODEBASE_PATH in .env points to your project root and the volume mount is correct in docker-compose.yml. If you deleted and re-created the project folder on the host (rm -rf + mkdir, a fresh clone into the same path, a sync tool that replaces the folder), the container still sees the old, now-empty folder. Run docker compose up -d --force-recreate so the mount points at the new one, then reindex. While a codebase that already has an index looks empty, CodeNavi refuses to reindex it and keeps the existing index. /health names the problem under codebases.<name>.root_problem, and a reindex that keeps less than half of the previous chunks prints a ⚠ index shrank warning.

"Connection refused" / "connection reset" from MCP client: The server binds to 127.0.0.1 inside the container by default. If your client runs in another container, on a different host, or reaches the server across a WSL2 port proxy, set CODENAVI_HOST=0.0.0.0 in .env and restart the container. Verify with ss -tlnp | grep 8765 — should show 0.0.0.0:8765, not 127.0.0.1:8765. The client half for a different host is Network → Beyond localhost; a Windows IDE talking to a WSL2 server is Windows → Self-managed WSL2 install.

Slow search on first query after restart: The embedding model loads lazily on first use when running in stdio mode. In HTTP mode (default), it pre-loads during startup.

Remote client gets 401 / times out / keeps "reconnecting": Remote access → Troubleshooting.

Chat returns 500: Could not resolve authentication method: The API key is read once at startup and only from .env — recreate the container after changing it: docker compose up -d --force-recreate. See Providers.

Index & search

Search returns nothing or looks stale: The index is behind the working tree. Run an incremental reindex (seconds) — reindex_incremental() from the agent, or docker compose exec codenavi python server.py --reindex. A zero-result response carries a coverage note when the codebase has materially unindexed file types; Supported languages lists what is indexed.

/health shows index_integrity: mismatch (or the log says index integrity MISMATCH): What is on disk no longer matches the fingerprint recorded at the last reindex — the mismatches list says what: a changed row count or Lance version, a missing or extra fragment file, a changed call-graph sidecar, or a failed PRAGMA quick_check. Causes are a partial restore, a disk fault, or something other than CodeNavi writing to index/. Search keeps answering from the index as stored. Run a full reindex (reindex(full=true)), which rebuilds both and records a fresh fingerprint; if the mismatch returns without a reindex in between, treat the data volume as suspect. unverified is not a fault: it means no fingerprint has been recorded yet (the first start after updating to the release that introduced the check) or the check has not run.

A folder keeps showing up in results that shouldn't be indexed: Add it to EXCLUDE_DIRS in the live data/settings.json, restart, reindex — Configuration → Excluding folders. Remember the repository's own .gitignore is already honoured.

doc_sources returns "Index predates doc ingestion": The source_type column was added after your index was built. Run a full reindex: reindex(full=true).

reindex_docs returns "DOCS_DIR not set": Set DOCS_DIR in .env to the host path of your documentation folder, then restart the container. The directory is mounted read-only at /app/external-docs inside the container.

PDF blocked by security scan: PDFs containing embedded JavaScript, auto-execute actions, or encryption are rejected. This is intentional — remove the dangerous content or use a different format.

A file was blocked by the security scanner and you disagree: Open the block report on the Security screen, allowlist the file's hash with a reason, reindex — Security model → Operating it.

GPU

GPU not detected, CUDA out of memory, autotune picked a slow tier: GPU compatibility for the card matrix and driver floors; CODENAVI_VRAM_BUDGET_GIB / ENCODE_BATCH_SIZE in Configuration when you share the card. Windows: Windows → Snags & fixes. AMD: ROCm notes in GPU compatibility.