8.4 — Troubleshooting
On this page
8.4 — Troubleshooting
Common issues when connecting and running your coding agent against VibeMap. Symptoms first, then likely cause, then fix.
Agent can't connect to the MCP server
Symptom
In Claude Desktop: no 🔨 hammer icon in the chat input, or the icon is there but vibemap isn't listed when you click it.
In Cursor / Windsurf: the MCP servers panel shows vibemap as red / disconnected.
Likely cause
- Wrong path in the MCP config — the JSON block was pasted into the wrong file or the file has a syntax error.
npxcan't reach the package — first-time install of@vibemap.ai/mcp-serverrequires network.- Missing or wrong API key — the
VIBEMAP_API_KEYenv var in the config is blank, expired, or revoked.
Fix
- Verify the config file location for your IDE (see Connect your AI coding agent for the exact paths).
- Try running the MCP server manually from your terminal:
npx -y @vibemap.ai/mcp-server. It should start and wait for stdin. If it errors, the message will tell you what's wrong (auth, network, npm cache, etc.). - Regenerate the API key on Account → Developer if you suspect it's stale.
"List my VibeMap projects" returns nothing
Symptom
Your agent connects (🔨 icon is there, server shows green in Cursor), but when you ask it to list projects you get an empty array or an error like "no projects found".
Likely cause
The API key belongs to a different account than the one that owns the project. Common with team setups.
Fix
- Check the email on Account → Profile matches the account that owns the project.
- If you're on a Team plan, the key must belong to a user with at least Viewer access to the project.
- Regenerate the key from the account that owns (or has access to) the project.
Agent claims an AC but no card moves on the Track tab
Symptom
You see "Agent vm_xxxxx claimed Y" in the Activity feed but the kanban board doesn't show the card moving from Ready → In Progress.
Likely cause
The realtime channel isn't getting updates through — usually a stale tab or a browser tab that's been backgrounded long enough for the connection to drop.
Fix
- Refresh the Track tab. The page does a full re-fetch on mount.
- If it persists across refreshes, check the browser console for WebSocket errors. The tracker uses Supabase realtime which requires WSS to
realtime.<your-supabase-host>. - Note that the Activity feed itself polls via HTTP every 5 seconds, so even when realtime is broken the feed shows current state.
Agent keeps claiming the same AC over and over
Symptom
Activity feed shows repeated "claimed" events for the same AC, no "submitted for review" follow-up.
Likely cause
The agent is hitting an error mid-implementation but not surfacing it cleanly — its loop logic catches the error, releases the claim, and tries again.
Fix
- Open the agent's chat / log in your IDE and look for the actual error. Common ones: missing dependencies in your repo, tests failing for a reason the AC didn't anticipate, file paths that don't exist.
- The AC's
payloadfield can be inspected via the REST API (GET /api/mcp/kanban/projects/<id>/events) if you want to see what the agent was reporting on each attempt. - If the AC's spec is genuinely under-specified, edit the Given/When/Then on the Features tab and re-plan to refresh dependencies.
"next ready" returns the same AC after I approved it
Symptom
You approve an AC, the card moves to Passed, but when the agent asks for next-ready it gets the same one back, or a downstream one that should have been unblocked stays in Ready.
Likely cause
- The hard-dependency edge you'd expect isn't actually in the database — the dependency-graph analyzer didn't infer it.
- There's a caching layer in the agent's MCP client (rare but possible).
Fix
- Open the AC's dependency sidebar (click the dep-count badge on the card in the Plan tab) and confirm the edges actually exist.
- If the edge is missing, re-run Re-analyze deps on the Plan tab. This refreshes the dependency-graph without redoing sprint allocation.
- Restart your agent / IDE to clear any client-side caches.
Sprint planning leaves many sprints empty / packs everything into Sprint 1–5
Symptom
You run Plan, get back 15 sprints, but only the first 5 have content. The fragmentation indicator on the Gantt lights up amber/rose.
Likely cause
This is a known LLM behavior pattern on the sprint-planner pipeline. The model commits to ~5 themed sprints for the real work and pads the rest. VibeMap's pipeline already drops the empty sprints automatically before showing them to you — if you're still seeing 5+10 empties, it means the planner output wasn't fully cleaned up. Try Re-plan.
Fix
- Click Re-plan on the Plan tab. The pipeline runs again with a fresh LLM call.
- If it happens consistently, your project probably genuinely fits in fewer sprints than the heuristic requested. The "Sprints planned" check in the Readiness panel still counts this as done — the smaller number is the right answer.
- For features that fragment across many sprints, look at the dependency-graph: the LLM may have marked some edges as "hard" when they could be "soft". This is the upstream cause and a future tightening opportunity.
Foundation overlays card stays editable after I click Approve
Symptom
You click "Approve selection" on the Foundation proposal card, see a success indication, but the card doesn't disappear.
Likely cause
This is a fixed bug — older versions of VibeMap had a client-side stale-state issue where the parent component didn't re-fetch after approval. The fix calls back into the parent's refresh function before invalidating server caches.
Fix
- Refresh the Track tab. If the card disappears after refresh but reappears on the next visit, the approve actually failed silently — open the browser network tab and re-click to see the actual HTTP response. The server returns
proposal_status_update_failedif the DB write failed.
Activity feed shows 500 errors / events stop updating
Symptom
Browser DevTools shows recurring 500 responses from /api/mcp/kanban/projects/<id>/events.
Likely cause
This was a real bug — the assertProjectAccess RPC was being called with the wrong parameter name. Fixed in the latest release.
Fix
- Make sure your VibeMap deployment is current.
- If you're self-hosted, pull the latest and redeploy.
Where to file new issues
If you hit something not covered here, capture: (1) the request URL + response body from the failing call, (2) the action you took just before, (3) whether the issue is local-dev or hosted. Open a GitHub issue or contact us via the in-app feedback widget.