Troubleshooting & FAQ

Common issues, error codes, and how to resolve them.

Daemon Connection Drops (EPERM / ENOENT)

If the ContextOS MCP client fails to connect to the daemon with an EPERM or ENOENT error on the socket path, it usually means the background daemon process crashed and left a stale socket file or PID lock.

Resolution: Check the daemon first, then stop and restart it if needed:

npx contextos daemon status
npx contextos daemon stop
npx contextos daemon start

clean removes indexed junk and does not stop the daemon or clear the whole index. Use clean --rebuild only when you intend to delete the local database; back up manual knowledge first.

Database Corruption

SQLite is extremely robust, but if your machine forcefully crashes during an active indexing write, the .contextos/index.db file can corrupt.

Resolution: ContextOS runs PRAGMA quick_check at startup. A corrupt repository database may be rebuilt automatically when no live daemon is using it, but this removes database-resident facts, feedback, and session history. Stop the project daemon and copy .contextos/index.db together with its -wal and -shm sidecars before recovery. The shared ~/.contextos/index.db is never destructively recovered while another project daemon might have it open; stop all relevant daemons, back it up, then remove and rebuild it deliberately.

Ignoring Large or Generated Files

If ContextOS is indexing massive auto-generated files (like package-lock.json or compiled output) and wasting CPU cycles, you can add them to an ignore list.

Resolution: ContextOS applies configured ignore patterns and the repository's .gitignore / .contextosignore rules during indexing and watching. If you want to ignore files specifically for ContextOS (but commit them to git), create a .contextosignore file in the root of your project:

# .contextosignore
dist/
build/
docs/out/
*.min.js

Slow Indexing Performance

If indexing is taking unusually long, ensure you are running Node.js 22.12.0 or later. ContextOS relies on modern native crypto hashing and worker threads. If you are indexing a mono-repo with millions of lines of code, the initial pass may take a minute, but subsequent incremental index runs will be sub-second as it only hashes and updates modified files.

CPU-only installation on Linux x64

The onnxruntime-node package can attempt to fetch optional CUDA provider files during installation on Linux x64. ContextOS can use its bundled CPU runtime, so skip that optional download on a CPU-only host:

ONNXRUNTIME_NODE_INSTALL=skip npm install -g @siddharthakatiyar/contextos

This is an install-time provider choice. It does not download or disable the local embedding model, and it should be omitted when CUDA execution is required. If a normal install fails while writing its temporary download, check the available space or quota for the system temporary directory.