Troubleshooting

Troubleshooting

Start with:

atlas version
atlas status
atlas doctor

atlas doctor also reports mcp_registrations health (assistant configs launching a missing or version-pinned binary — fix with atlas bootstrap) and accepts --deep for a page-level integrity scan (PRAGMA quick_check) that catches on-disk corruption reads silently tolerate.

Record the repository path, database path, Atlas version, and exact command before changing data.

Installation

atlas: command not found

command -v atlas
echo "$PATH"

For Homebrew:

brew list --cask atlas
brew reinstall --cask aziron-ai/atlas/atlas

For npm:

npm prefix -g
npm install -g @aziron/atlas

npm binary download fails

Confirm the requested version exists on GitHub Releases, then check proxy and GitHub access. Pin a published version instead of a version that is still being released.

macOS blocks a manual binary

Prefer the Homebrew cask. For a trusted, checksum-verified manual binary:

xattr -dr com.apple.quarantine /usr/local/bin/atlas

Repository and Freshness

Results come from the wrong repository

Pin scope:

atlas --repo /absolute/path status

For a shared database, use the repository ID shown by atlas status.

Results are stale

atlas index .
atlas status

If the status remains stale:

atlas doctor
atlas index . --reindex

workspace_required from MCP

Supply a workspace root, workspace, repo_id, or launch-time --repo. Atlas does not silently select a repository for scoped requests.

Database and Retrieval

SQLite is busy or locked

Stop atlas serve, atlas watch, and supervised MCP processes. Inspect the owner:

lsof "$PWD/.atlas/atlas.db"

Run maintenance serially after all writers exit.

The lexical sidecar (sql_fallback and the index-time warning)

Atlas keeps two stores under .atlas/: the graph database (atlas.db, SQLite — symbols, callers, routes, impact) and a separate lexical sidecar (.atlas/lexical/, a Bleve BM25 index) that powers fast text search. Graph queries never need the sidecar; only text and keyword search does.

Two symptoms point at the same thing:

• atlas index warns lexical sidecar unavailable, indexing without it (lazy backfill will heal): ... — a warning, not a failure. The graph index still built.
• Search results report degraded: true / retrieval_mode: sql_fallback — text search is answering from a SQL scan instead of BM25 (correct, but slower and lower quality). Symbol, caller, ref, route, and impact queries are unaffected.

Both mean the sidecar was empty, wedged, or locked. The common cause is another Atlas process — a running atlas serve, atlas watch, or a supervised/stale MCP session — holding the sidecar's exclusive lock; the open waits about two seconds (a bounded timeout), then Atlas proceeds without it rather than failing the whole run. Running atlas index by hand while a server watches the same repo is the usual trigger.

It self-heals: in serve/watch mode a lazy backfill rebuilds the sidecar once the lock frees. To fix it now, stop the other Atlas processes and rebuild:

atlas compact --rebuild-lexical
atlas doctor

Why atlas status looks clean while atlas doctor flags it: atlas status reports version and contract health only (schema, index-format, lexical, and MCP contract versions plus snapshot format) and never opens the sidecar. atlas doctor checks runtime health, opens the sidecar, and reports lexical_degraded when it is empty or wedged. If search behaves oddly but status is clean, run atlas doctor.

Upgrade reports schema or index drift

atlas migrate
atlas status --schema
atlas index . --reindex

Back up .atlas/ before migration or downgrade testing.

Semantic search falls back to lexical

atlas index . --enable-vectors
atlas status

Also verify semantic retrieval configuration with atlas config list.

MCP and Assistants

Assistant does not list Atlas tools

atlas bootstrap --dry-run
atlas doctor --verify atlas

Apply bootstrap if needed, then fully restart the assistant.

MCP list is fast but calls are slow

An index or exclusive maintenance task may be running:

atlas status
atlas doctor

Wait for indexing, disable duplicate watchers, or adjust ATLAS_MCP_CALL_TIMEOUT only after confirming the root cause.

HTTP 401 or 403

Supply the bearer token:

curl \
  -H "Authorization: Bearer $ATLAS_API_TOKEN" \
  http://127.0.0.1:3099/api/v1/status

For browser clients, also configure ATLAS_MCP_ALLOWED_ORIGINS.

Server

Port 3099 is already in use

lsof -nP -iTCP:3099 -sTCP:LISTEN

Stop the existing process or select another address with atlas serve --help.

healthz passes but readyz fails

Atlas is running but cannot complete a lightweight engine request. Check for an active index, database lock, or maintenance operation.

Before Deleting Data

1. Stop every Atlas process.
2. Confirm the exact database and repository paths.
3. Back up the full .atlas/ directory.
4. Run atlas doctor.
5. Attempt migration, lexical rebuild, or reindex first.

Delete local Atlas data only when a complete reset is intended.

Two Atlas writers at once

atlas: lexical segment-version probe failed (…: timeout) — opening anyway

Writer-vs-writer contention on the lexical sidecar — typically a manual atlas index beside a running serve/watch. One-off and self-healing (the run continues; the next uncontended index or atlas compact --rebuild-lexical restores BM25). Recurring constantly → quiesce the extra writer.

Silent disk corruption (doctor --deep)

SQLite reads pages lazily, so a corrupted store can keep answering reads until the next write fails with database disk image is malformed (11). From v0.1.43, atlas doctor --deep runs PRAGMA quick_check and escalates to status: "db_corrupt" naming the damaged pages. Recovery: restore .atlas from a backup, or delete .atlas and run atlas index --reindex.