# Troubleshooting

> Fix the errors you are most likely to hit when starting the collector, sending telemetry and running browser checks.

Find your symptom, then apply the fix. Add `--debug` (or `BLOP_DEBUG=1`) to any command for a stack trace.

## `blop up` says port 27811 is in use

`error: Port 27811 is used by another program` (exit 2). Another program, or a collector started for another project, holds the port.

```bash
lsof -iTCP:27811 -sTCP:LISTEN
```

Stop that program, or start on another port: `blop up --port 27812`. A project collector keeps its port in `.blop/monitor.json`.

## My app's traces do not show up in Blop

The app exports somewhere else, or over OTLP/gRPC, which the collector does not accept. Run `blop doctor`: it sends a probe span and names the failing check with a fix. Then point the app at `http://127.0.0.1:27811` with `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf` or `http/json`, or start it with `blop run -- <your dev command>`, which sets both. See [Collector HTTP API](/reference/http-api/#otlp-ingestion).

## `blop test run` says "No Blop spec files found"

No file matched `**/*.blop.ts` or `**/*.blop.tsx`, or your `include` globs. Rename the file to end in `.blop.ts`, pass it directly (`blop test run tests/my-check.ts`), or fix `include` in [`blop.config.ts`](/reference/configuration/#discovery-options). `blop test init` creates a starter check.

## `blop claude` says a path "is a symlink, so Blop will not edit it"

The agent's config file, or a directory above it, is a symlink, and Blop refuses to write through links. It still starts the agent, without capture. A common cause is a home directory reached through macOS's `/var` or `/tmp` links. Use the real path, then rerun:

```bash
export HOME="$(cd "$HOME" && pwd -P)"
blop claude
```

If the named path is the config file itself, replace the link with a copy of its target. The same applies to `blop codex` and `blop opencode`.

## `blop test` fails with "Unknown file extension .ts"

Node.js is older than 22.18 and cannot load TypeScript checks, so both `blop test list` and `blop test run` fail. Upgrade Node.js, or run with `NODE_OPTIONS=--experimental-strip-types`.

## `blop test` says `@blopai/test` is not installed

The CLI cannot find its optional browser check package (exit 2). Reinstall `@blopai/cli` with optional dependencies enabled where it is installed, or add `@blopai/test` to the same project as in [Run browser checks](/checks/#write-and-run-your-first-browser-check). A separate global `@blopai/test` does not help a project-local CLI. If the error names another module, that is the real cause.

## Browser check fails with "No model configured" or "Missing API key"

`No model configured for the blop agent loop` means no model was set; there is no default. Set `BLOP_AGENT_MODEL` (and `BLOP_AGENT_PROVIDER`, which defaults to `openrouter`), or pass `--model`.

`Missing API key for provider` means no key reached the runner. Pass `--api-key`, set `apiKey` in `blop.config.ts`, or export `BLOP_AGENT_API_KEY`; that is the precedence order, and environment or config keeps the secret out of shell history. Provider key names are never read: `export BLOP_AGENT_API_KEY="$OPENAI_API_KEY"`. See [Agent providers](/checks/providers/).

## Playwright says `Executable doesn't exist`

The browser is not installed for the Playwright version `@blopai/test` uses. Install it with this pinned command, not the unpinned `npx playwright install` the error suggests, which can fetch a browser for another version. Add the same step to CI before `blop test run`:

```bash
pnpm dlx playwright@1.61.1 install chromium
```

## Browser check ends as `failed`

The agent finished with an unmet goal; check the goal, target and data before blaming the app. Read `reason` in `.blop/results.json`, then the last `tool_result` events in `.blop/events.jsonl`, then screenshots. Rerun with `--capture-screenshots` for one per action. `error` means the run itself broke: timeout, crash or provider failure. See [Result fields](/reference/runner/#result-fields).

## Browser check says the agent appears to be stuck

The agent repeated actions without progress, stopped without calling `finish_test`, or hit `--max-steps`. Rerun with `--verbose` to stream events, and watch `.blop/events.jsonl` for the last `tool_result`. Make the goal concrete or split it into one check per user journey; raise `--max-steps` only when the journey is genuinely long.

## Browser check passes when the page is broken

The goal is too vague, so the agent passes optimistically. Rewrite it:

| Instead of | Write |
|---|---|
| "Test the homepage." | "Verify the heading `Welcome` and the `Sign up` button appear in the header." |
| "Click the button and check it works." | "Click `Submit` and verify the URL is `/thanks` and the heading reads `Order confirmed`." |
| Several journeys in one check | One check per user-visible outcome |
| "Don't fail." | "Pass only if every verification succeeds; otherwise fail and say why." |

More rules are in [Write goals the agent can act on](/checks/#write-goals-the-agent-can-act-on).