VibeMap Logo

Troubleshooting

On this page

Troubleshooting

Common issues when connecting and running your coding agent — symptom, likely cause, fix. · Recommended

If something isn't working during handoff, find the symptom below. Most problems are a config typo, a stale API key, or a browser tab that's lost its realtime connection.

Agent can't connect to the MCP server

Symptom — No hammer icon in Claude Code, or vibemap shows red/disconnected in Cursor/Windsurf.

Likely cause

  1. The config was pasted into the wrong file, or the JSON has a syntax error.
  2. npx can't reach the package (first install of @vibemap.ai/mcp-server needs network).
  3. The VIBEMAP_API_KEY in the config is blank, expired, or revoked.

Fix

  • Re-check the config file location and JSON validity for your IDE (see Connect your IDE).
  • Run the server manually: npx -y @vibemap.ai/mcp-server. It should start and wait for stdin; any error message tells you what's wrong.
  • Regenerate the key at Account → Developer if you suspect it's stale, then fully restart the IDE.

"List my VibeMap projects" returns nothing

Symptom — The agent connects, but listing projects returns an empty array.

Likely cause — The API key belongs to a different account than the one that owns the project (common with team setups).

Fix

  • Confirm the email on Account → Profile matches the account that owns the project.
  • 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 can access) the project.

MCP list tools return empty for a project you 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_ token isn't reaching the API (malformed env var, extra whitespace, wrong key name), so reads fall back to an anonymous client that row-level security blanks out.

Fix — Confirm the env var is exactly VIBEMAP_API_KEY and the value starts with vm_. Re-test with "List my VibeMap projects, then list features for project X" — if the first works and the second is empty, regenerate the key.

Agent claims an AC but no card moves on the board

Symptom — The Activity feed shows "claimed" but the board doesn't update.

Likely cause — The realtime channel dropped — usually a stale or long-backgrounded browser tab.

Fix — Refresh the Development page (it re-fetches on mount). The Activity feed itself polls over HTTP every few seconds, so it shows current state even when realtime is down. If it persists, check the browser console for WebSocket errors.

Agent keeps claiming the same AC over and over

Symptom — Repeated "claimed" events for one AC, never a "submitted for review".

Likely cause — The agent hits an error mid-implementation, releases the claim, and retries.

Fix — Open the agent's chat/log in your IDE for the real error (missing deps, failing tests, wrong paths). If the AC's spec is genuinely under-specified, edit its Given/When/Then on the Features page and re-plan.

"Next ready" returns an AC that should be unblocked/blocked

Symptom — You approve an AC but the agent gets the same one back, or a downstream AC stays in Ready.

Likely cause — The expected hard-dependency edge isn't in the database, so the graph didn't unblock/order it correctly.

Fix — Open the AC's dependency side sheet (click the dependency badge on the Sprint Planning page) and confirm the edges exist. If one's missing, run Re-analyze deps there. Restart the agent to clear any client-side cache.

Sprint planning leaves many sprints empty

Symptom — You get back more sprints than have content; the Gantt lights up amber/rose.

Likely cause — A known LLM pattern where the planner pads extra sprints. VibeMap drops empties automatically; a few can slip through.

Fix — Click Re-plan on the Sprint Planning page. If it recurs, your project genuinely fits in fewer sprints — the smaller number is the right answer. Persistent fragmentation usually points to over-eager hard dependencies; start with Re-analyze deps.

Generation fails with a token-limit message

Symptom — A generation (in-app, agent chip, or codebase analysis) returns "you've hit today's token limit" or a 402.

Likely cause — You've exhausted the plan's token budget. Budgets run per rolling 5-day window as well as per month, and the Free plan is small enough (plus a 75-generation throttle per window) that one large project can consume it.

Fix — Check Billing → Usage & Analytics (Billing is its own top-level section, not part of Account). Wait for the reset, upgrade, or switch to an auto-tier model — auto and premium budgets are tracked separately. See Account and billing.

Generation looks stuck at "Generating…" forever

Symptom — A progress bar sits at the same percentage for minutes; refreshing doesn't obviously help.

Likely cause — A realtime progress event was missed (tab refresh or dropped WebSocket). The generation usually finished server-side.

Fix — Refresh the page — the app checks the task's real status on load and self-heals a stale lock. If a duplicate-generation warning appears on retry, the original is still running; give it a minute. A background sweeper releases genuinely stuck generations after ~15 minutes.

Where to file new issues

If you hit something not covered here, capture: (1) the request URL + response body from the failing call, (2) what you did just before, (3) whether it's local-dev or hosted. Open a GitHub issue or use the in-app feedback widget.

⚡ Power-user hints

  • Read the status code before the message. A 402 is an entitlement refusal — branch on the code field, PLAN_UPGRADE_REQUIRED or TOKEN_BUDGET_EXCEEDED. A 403 means the key isn't allowed to do that at all: wrong account, or an agent key trying to resolve its own review. Nothing downgrades automatically when premium tokens run out; the run is refused.
  • Prove the server before you blame the IDE. npx -y @vibemap.ai/mcp-server in a terminal should start and sit waiting on stdin. If that works, the fault is in your config file or your key, not the package.
  • The Activity feed is the tiebreaker. It polls over HTTP while the board rides realtime. Feed advancing but board frozen = your browser tab. Neither moving = your agent.

What's next