# Troubleshooting

> Diagnose widget, hub, bridge, project-routing, and watcher-lease states.

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:

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

## MCP server offline

Start the hub and check its public health route:

```bash
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.

## Waiting for an agent

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:

```bash
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`.

## The widget does not appear

- 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.