--- title: "Troubleshooting" description: "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." canonical: "https://scalebrowser.net/docs/ops/troubleshooting" --- > ## Documentation Index > Fetch the complete documentation index at: https://scalebrowser.net/llms.txt > Use this file to discover all available pages before exploring further. # 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](/docs/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](/docs/coherence). ## 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](/docs/agents/mcp-clients/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](/docs/agents/wsl-and-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](/docs/agents/mcp-server#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](/docs/errors#the-mcp-shape). ## 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](/docs/verify). **`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](/docs/errors): every code, with its remedy. - [Test your setup](/docs/verify): measuring instead of guessing. - [Monitoring & metrics](/docs/ops/monitoring): catching these before they surprise you.