Troubleshooting
The failures that look like something else: a launch that is refused, a client that cannot connect, an agent that says a tool does not exist, and a profile that behaves differently from yesterday.
Ordered by what people actually hit. Every one of these is a case where the symptom points somewhere other than the cause.
A profile will not start
Read the error code first. It says which of five different problems you have, and four of them are not what the fifth looks like.
| Code | What to do |
|---|---|
4011 | Sign this machine in. Nothing runs without an account. |
4004 | No engine for this profile's tier. engine list, then engine install. |
4005 | The pre-launch check refused it. The message names the reason; retrying unchanged fails identically. |
4002 | The proxy or geo check. Re-check the proxy, or change geo_mode. |
4013 | The exit address belongs to another profile. Wait, or draw again. |
4003 | This machine is full. Stop something. |
4008 | Your subscription is full, across all machines. Release one anywhere. |
4012 | The profile is open on another machine. Close it there, or take it over. |
Full text on Errors.
"It works for some profiles and not others"
That reads like flakiness and usually is not. A new profile draws its engine version from the whole installed set, deliberately, so a fleet is not uniform. If one installed engine is unsigned or fails verification, a fraction of new profiles become unlaunchable: exactly the ones that drew it.
Run engine verify on each installed version. engine list shows what is there.
"Everything was fine until I ran a test"
Chromium writes into its own installation directory, and the provenance gate reads that as tampering. A dictionary download once refused every profile start on a machine.
engine verify names the file. Reinstalling the engine is the fix.
The host has no real GPU
The daemon boots, serves the whole API, and refuses every launch. There is no software-rendering fallback, because software rendering is visible from the page whatever the profile claims. See Coherence & proxies.
A client will not connect
"It connected and every call is unauthorized"
Two different causes, and they need opposite fixes.
4010 means the bearer token is wrong. Re-read it from the data directory or the app.
Everything unauthorized over stdio usually means the process attached to a different daemon. Without --data-dir or --config it looks in the default data directory, which is not the one the desktop app uses. If an old runtime.json is sitting there, it finds whatever holds that address. See Claude.
"The server does not appear at all"
In Claude Code, an entry with a url but no "type": "http" is read as a stdio server and skipped.
"It says the host is not allowed"
The MCP transport checks the Host header, which is what stops a web page on another origin from driving your loopback daemon. Loopback and the configured bind are accepted out of the box; a public name needs adding to [mcp] allowed_hosts.
From WSL or a container
127.0.0.1 inside WSL is the Linux side, not Windows. Forwarding runs the other way only. See WSL & containers.
The agent says a tool does not exist
Three possibilities, in order of likelihood.
The daemon does not serve it. The default is core alone, so an agent cannot even list a profile. Add management: see the tool set. Changing it needs a restart, on purpose.
Read-only mode is on. Every mutating tool is absent from the listing and refused on call, lease_profile included.
The client's own tool search did not surface it. Claude prefixes every name (Scalebrowser:profile.list) and searches before it calls, and with a large catalog it has answered "there is no such tool" for tools it listed in full seconds later. The fully prefixed name works. Serving fewer profiles makes it rarer.
A tool call failed and I do not know what happened
Read effect, not the message.
none means nothing happened. confirmed means it did. possible and partial mean the outcome is unknown, and retryable is false for exactly those, because a retry there is what posts twice. Take a snapshot and look before acting again. See Errors.
The profile behaves differently than yesterday
The exit moved
Check the last exit_guard_changed event. severed means the address moved onto one another profile owns and the wire was cut, deliberately and permanently for that session. unverified means three probes in a row got no answer, and nothing was cut.
The proxy changed underneath you
A PATCH touching host, port, kind or credentials drops the cached country and health, and the geo gate then has nothing to judge by until you re-check.
The engine changed
An app update brings the engine up to what the new client requires. engine list shows the pin; engine rollback returns to the previous build without a download.
Nothing here matches
Two instruments before you guess.
Run the same engine with no profile configuration. It answers what your host really is, in one launch, and every fingerprint judgement is a difference between two readings.
Run the built-in audit against the running profile: POST /v1/profiles/:id/audit. See Test your setup.
curl cannot tell a wrong address from a bot wall. Both answer 403. If a page will not load, drive a profile at it rather than concluding anything from the transport.
Next
- Errors: every code, with its remedy.
- Test your setup: measuring instead of guessing.
- Monitoring & metrics: catching these before they surprise you.