Troubleshooting
Run codeloop doctor first. It validates the entire activation chain — global MCP config, agent rules, project config, runtime tooling (ffmpeg, adb, xcrun, simctl, screencapture, xdotool, xwininfo, PowerShell, Playwright) and backend reachability — and prints a one-line remedy for every failure. Almost every issue below is covered by the doctor output; this page is the symptom-first index.
Init & auth
| Symptom | Fix |
|---|
codeloop init creates files but Cursor does not show MCP tools. | Restart Cursor. Confirm .cursor/mcp.json contains a codeloop entry; if not, re-run codeloop init. See Cursor setup. |
codeloop_init_project is the only tool that fires. | Always-on activation hasn't been registered. Run codeloop install-cursor-extension or paste the User Rule manually under Cursor settings. See Cursor extension. |
npx codeloop auth opens the browser but never receives the key. | A local firewall is blocking the loopback callback port. Use codeloop auth --no-browser to fall back to email / password prompts. |
codeloop statussays "not authenticated" but you have CODELOOP_API_KEY set. | Confirm the env var is exported in the same shell and is a real key (cl_live_…, cl_test_… for local development). On macOS / Linux add it to ~/.zshrc; on Windows use setx CODELOOP_API_KEY. |
Verify
| Symptom | Fix |
|---|
codeloop_verifysays "project not initialized". | Call codeloop_init_project (MCP) or npx codeloop init (CLI) first. Or set CODELOOP_PROJECT_DIR to the absolute project path. |
| Verify never finds tests on a Python / Ruby / Rails project. | Add a plugin entry — see Plugin SDK. |
Web project verify skips Playwright. doctorsays "Playwright Chromium not installed". | npx playwright install chromium --with-deps. |
Screenshots & video
| Symptom | Fix |
|---|
codeloop_capture_screenshot returns captured: false. | Wrong app name, multi-monitor mismatch, or missing OS permission. On macOS grant Screen Recording + Accessibility to your terminal / IDE. |
| Recorded video is 0 bytes or under 1 KB. | ffmpeg cannot capture. On Linux make sure XWayland is enabled and ffmpeg has x11grab support. On Windows make sure no group policy blocks gdigrab. |
codeloop_interaction_replaysays "ffmpeg not found". | Install ffmpeg per Cross-OS runbook. |
Gate check
| Symptom | Fix |
|---|
Gate returns continue_fixing but everything looks fine. | UI projects need both screenshots and video evidence. Run codeloop_capture_screenshot + codeloop_start_recording / stop_recording / interaction_replay before re-gating. |
Gate fails with design_compare_evidence. | Add references under designs/ or configure .codeloop/figma.json, then run codeloop_design_compare. Threshold is 0.85 by default — tune in .codeloop/config.json. |
Dashboard & CI
| Symptom | Fix |
|---|
npx codeloop dashboard exits with EADDRINUSE. | Pass --port 4000 or set DASHBOARD_PORT=4000. |
| GitHub Action posts but never updates the badge. | Make sure publish-badge: true is set and the API key has badge permissions. See GitHub Action. |
| GitHub Action keeps timing out. | Increase the job timeout-minutes. The default verify + gate cycle on a medium project is 8–15 minutes. |
Still stuck?
Open an issue with the full output of codeloop doctor plus npx codeloop verify --debug at github.com/codelooptech/codeloop.
Related