Troubleshooting

Start with the exact status shown in the widget's Agent or Settings panel.

MCP not configured

The widget has no beaconUrl. Mount it with both routing values:

<VibeCheck
  beaconUrl="http://127.0.0.1:4200"
  projectId="my-storefront"
/>

MCP server offline

Start the hub and check its public health route:

npx -y @wcgw/vibe-check-mcp@0.3.0 hub
curl http://127.0.0.1:4200/api/health

If you changed the port, update the hub's VIBE_CHECK_PORT, the bridge's VIBE_CHECK_HUB_URL, and the widget's beaconUrl together.

This is good browser-to-hub connectivity with no watcher. In an agent session, call list_projects, then watch_for_issue with the displayed project_id. The status changes only after the lease is acquired.

Agent disconnected

The watcher missed heartbeats. Restart or reconnect the MCP client; after the 15-second lease expiry, call watch_for_issue again.

A second agent was rejected

The original watcher remains the owner. Continue in that session, or call release_project there before changing sessions. Retrying from the rejected session does not steal the lease.

`project-ambiguous`

Several dev servers are active. Call list_projects and pass the intended project_id. Give each widget a stable, unique ID instead of relying only on its localhost port.

Port 4200 is already in use

A VibeCheck hub may already own it; reuse that one for all projects. To choose a different port:

VIBE_CHECK_PORT=4300 npx -y @wcgw/vibe-check-mcp@0.3.0 hub
VIBE_CHECK_HUB_URL=http://127.0.0.1:4300 npx -y @wcgw/vibe-check-mcp@0.3.0 connect

The bridge does not appear in the agent

Restart the client after changing MCP configuration.
Confirm its command ends in connect.
Start the hub first; connect fails fast when the hub is unavailable.
In Claude Code, run claude mcp list.

Confirm it is mounted and not gated out by the current environment.
<PerfToggle /> starts as a collapsed pill; press Alt+Shift+V.
For Next.js, load it client-side with ssr: false.

A metric is unavailable

VibeCheck feature-detects browser APIs. Memory and LoAF attribution are Chromium-only; unsupported Web Vital entry types remain null. This does not prevent hub or agent communication.