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: ContextOS is designed to auto-heal from these states. You can force a full restart by running:

npx contextos clean

This will shut down the daemon, delete the stale sockets, and clear the local index.

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: Do nothing. ContextOS automatically runs a PRAGMA quick_check every time it boots. If it detects corruption, it silently deletes the broken DB and rebuilds it from scratch. Since ContextOS is just an index of your local files, no data is actually lost.

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 respects your .gitignore automatically. 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 18+. 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.