Troubleshooting

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.

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.

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

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

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:

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.

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.