Common Failures & Remediation Actions
Diagnose compilation blocks, folder permission boundaries, stale configurations, and runtime timeouts.
Installation Failure Matrices
Review the exact errors encountered during setup, along with detailed remedies to fix them:
| Error / Issue | Detection Logs | Remedy / Action Plan |
|---|---|---|
| Go not installed | "build failed: exec: 'go': executable file not found in $PATH" | CostAffective installer compiles code from source. Run sudo apt install golang-go or download Go from golang.org. |
| Binary folder missing | "CostAffective was not installed to ~/.local/bin/costaffective" | Your system is missing the local binary bin folder. Run: mkdir -p ~/.local/bin and verify writing permissions. |
| Binary not executable | "exists but is not executable" | Executable bit is missing. Fix via chmod +x ~/.local/bin/costaffective or run costaffective install --repair. |
| Binary corrupted | "did not respond to --version" | Binary did not execute cleanly. Run costaffective install --repair to trigger a clean rebuild. |
| Relative binary path | "uses a relative binary path" | Subprocesses launched by editors require absolute paths. Run costaffective install --repair to write absolute paths into configs. |
| Invalid JSON config | "Invalid JSON in ~/.cursor/mcp.json" | Cursor config is corrupted. Re-run costaffective install --repair to rebuild the config structure. |
| MCP Handshake Failure | "Server did not respond to initialize" | Verify binary launch works outside the IDE by running costaffective serve. If it crashes, inspect dynamic library attachments. |
| Index Directory Locked | "Index directory is not writable" | Your user account does not have write access to the project folder. Run sudo chown -R $USER:$USER . on the workspace directory. |
Runtime Maintenance
Database Sync Locks
WAL journaling prevents read/write locks. If the SQLite engine gets locked due to an unexpected IDE exit, delete database locks:
rm -f .mycli-fts/*.db-journalinotify Watch Limits on Linux
If you index large repositories and hit system file watcher limits, increase max watches:
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p