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.
Generation fails immediately with a token-limit message
Symptom
Any generation (in-app buttons, agent chips, or vibemap_analyze_codebase) returns an error like "You've hit today's token limit" or a 402 response.
Likely cause
You've exhausted the plan's daily or monthly token budget (auto or premium tokens — see 9.1 Account & billing for the per-plan numbers). Free-plan daily budgets in particular are small enough that one large project can consume them.
Fix
- Check Account → Billing for your current usage.
- Wait for the daily reset, upgrade, or switch the generation to an auto-tier model (premium and auto budgets are tracked separately — running out of premium tokens doesn't block auto-model generations).
Generation looks stuck at "Generating…" forever
Symptom
A progress bar sits at the same percentage for many minutes; the button stays disabled; refreshing doesn't obviously help.
Likely cause
The realtime progress event (Pusher) was missed — typically after a tab refresh or a dropped WebSocket mid-generation. The generation itself usually finished server-side.
Fix
- Refresh the page: the app checks the task's real status in the database on load and self-heals a stale "generating" lock — a hard refresh always gives a clean state.
- If a duplicate-generation warning appears when you retry, the original run is still active server-side; give it a minute. The server rejects true duplicates, so you can't double-bill yourself by retrying.
- A background sweeper also releases genuinely stuck generations after ~15 minutes.
MCP list tools return empty for projects you definitely own
Symptom
vibemap_list_features (or any list tool) returns [] for a project that clearly has content, while vibemap_list_projects works.
Likely cause
Your vm_ personal access token isn't reaching the API (malformed env var, extra whitespace, wrong key name in the MCP config), so reads fall back to an anonymous client that row-level security blanks out — an empty list rather than an error.
Fix
- Confirm the env var in your MCP config is exactly
VIBEMAP_API_KEYand the value starts withvm_. - Re-test with: "List my VibeMap projects, then list features for project X" — if the first works and the second is empty, it's almost always the authz path; regenerate the key.
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.