Troubleshooting

Troubleshooting

Start with columbus doctor — it checks the binary, git, ripgrep, ast-grep, grammars, config, data dir, database, and index in one shot. See Command: doctor.

"no .columbus.json found" (exit 3)

error [NOT_INITIALIZED]: no .columbus.json found
  hint: run columbus install

You're not in an initialized project. Run columbus install (it also runs the first index). See Command: install.

A new symbol/file isn't found

The index lags the working tree. Reindex the changes:

columbus reindex --changed     # fast: only dirty files
columbus reindex               # incremental

Note: results you do get are never stale (snippets are live) — this only affects discovery of new entities. See Never Stale: Live Reconstruction.

"symbol not found" (exit 1)

The name doesn't resolve. Try columbus search <name> to find the right symbol, or disambiguate with columbus show symbol <name> --in <path>.

Index writer locked (exit 4)

Another reindex is running. This is transient and retryable — back off briefly and retry, or wait for the other run to finish.

Build fails with cgo/fts5 errors

Columbus needs a C compiler and must be built with -tags fts5 and CGO_ENABLED=1. Use the Makefile, which pins both. Ensure a working C toolchain (and zig for cross-compiles). See Development & Testing.

go install worked but columbus isn't found

$(go env GOPATH)/bin isn't on your PATH:

export PATH="$(go env GOPATH)/bin:$PATH"

Memory shows "drift"

Expected and benign — the code an evidence anchor points at moved. Drift is a warning, never fatal (exit 0). Re-anchor with columbus memory update context <id> --add-evidence …. See Project Memory.

Color is missing / unwanted

Color follows --no-color, NO_COLOR, FORCE_COLOR, TERM=dumb, CI, then TTY detection. See Color & Environment.

Still stuck?

Open an issue with columbus doctor --json output: https://github.com/orafaelfragoso/columbus/issues

Related

Command: doctor · Exit Codes · FAQ