# CLI troubleshooting

> Diagnose installation, local capture, pairing, forwarding, and policy behavior one stage at a time.

Source: https://docs.agentbeam.com/agent-cli/troubleshooting

Start by separating the local CLI, collector, assistant hook, and remote workspace. Each can be healthy while another is disconnected. Avoid deleting the Beam data directory to solve a pairing or service problem; it contains retained events, credentials, and policy state.

## beam is not found

Verify Node meets the package requirement and `@agent-beam/beam` is installed. Confirm the npm global binary directory is on PATH. A desktop assistant or MCP host may use a different environment from the terminal; configure a reviewed absolute executable path where necessary.

## Collector is unreachable or the port is busy

Check `beam service status` if using a background service. Do not run a second foreground collector on the same port. Confirm `BEAM_PORT` and `BEAM_COLLECTOR_URL` refer to the same local listener and that the URL uses HTTP at `127.0.0.1` or `localhost`.

Use `beam service logs` to locate diagnostics. With a custom data directory, make sure client commands read the token belonging to that collector.

## Studio loads but shows no data

The HTML shell does not require authentication, but the data API does. Reopen with `beam studio` to pair against the intended collector. Use **Disconnect** to clear stale browser pairing. Different ports have separate local storage.

Then verify a real harmless tool action from a supported assistant. `beam agent list` reports adapter support, not proof that the assistant actually invoked its hook. Check the native config and process PATH.

## Local activity is missing from the dashboard

Run `beam whoami` and `beam account` to confirm the workspace and device status. An unconnected collector stays local. An enrolled collector batches forwarding and flushes partial batches after inactivity, so quiet activity can appear later.

Forwarding is best-effort, without a durable retry queue. Network or server failures can leave history only on the machine. Preserve a local redacted export rather than assuming reconnect automatically replays every missed record.

## A device can't connect: plan limit

`beam connect` stops with a message like "Every seat on this workspace's plan is taken". Free covers 3 people and 5 devices, Pro one person and 10 devices, and Team grows with its seats. An owner, admin or billing manager can remove unused devices under **Devices**, or upgrade or add seats under **Plans**, then run `beam connect` again. Local protection keeps working meanwhile. See [Plans, billing & enterprise](https://docs.agentbeam.com/agent-cli/subscription#who-takes-a-seat).

## A policy did not block

Run `beam sync` and confirm the expected workspace policy version. Check mode, matching baseline fields, cached expiry, and whether the assistant uses the supported PreToolUse deny contract. Only Claude Code and Codex denial output is wired in the public CLI.

Structured dashboard rules are not consumed by the current public evaluator. Other agents receive diagnostic notes for deny decisions. Missing, unreadable, or expired policy allows the action. Agent policy is not a substitute for an OS sandbox or complete endpoint enforcement.

## Scan or MCP tool fails

Use valid JSON with `--mcp`; respect the 2 MB file and 500,000-character text bounds. Saved scans also face the collector request-size limit. For MCP, verify `BEAM_BIN`, absolute file paths, and the subprocess's 15-second/5 MiB limits.

When contacting support, include versions, platform, command name, redacted error, collector port, and whether local or remote behavior failed. Keep tokens, enrollment codes, raw prompts, and private files out of diagnostics.