> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trylaunchkit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Symptoms, causes, and fixes for BYO sandbox runtimes

Start with the worker's own diagnosis on the worker host:

```bash theme={null}
launchkit-worker doctor
```

## Bridge mode

| Symptom                                                                                         | Likely cause                                                                                        | Fix                                                                                                                       |
| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `doctor` fails the cloud-reachability check                                                     | Egress to `https://api.trylaunchkit.ai` blocked, or wrong `LAUNCHKIT_API_URL`                       | Allow outbound HTTPS from the worker host; check the URL has no typo and uses `https://`                                  |
| `doctor` reports the key invalid or unauthorized                                                | Key revoked, or `LAUNCHKIT_RUNTIME_ID` does not match the runtime the key was minted for            | Confirm both values against what your LaunchKit contact delivered; a key only works for its own runtime                   |
| Daemon exits immediately and systemd does not restart it                                        | **HTTP 426**: worker version below the runtime's floor                                              | Install the newer wheel provided by your LaunchKit contact, then `systemctl restart launchkit-worker`                     |
| `doctor` warns or fails on clock skew                                                           | Host clock drift above 30s (warn) or 300s (fail)                                                    | Fix NTP on the worker host                                                                                                |
| `doctor` fails the plane-reachability check                                                     | Wrong `E2B_DOMAIN`/`E2B_API_URL`, plane down, or TLS failure to an intranet CA                      | Verify the plane variables; for a private CA set `SSL_CERT_FILE` (see [Compatibility](/en/runtimes/compatibility))        |
| `doctor --probe` fails the pause check                                                          | Plane does not support pause-with-disk-parity (CubeSandbox older than v0.5.0)                       | Upgrade the plane, then re-run the probe                                                                                  |
| `doctor --probe` fails the snapshot check, or the runtime shows a `snapshot probe failed` error | Plane cannot snapshot/fork (CubeSandbox older than v0.5.1), or the worker wheel is older than 0.5.0 | Upgrade the plane to >= v0.5.1 and the worker wheel to >= 0.5.0, re-run `doctor --probe`, then have the runtime re-probed |
| Runtime shows workers offline in LaunchKit                                                      | Daemon not running, or egress dropped                                                               | `systemctl status launchkit-worker` and `journalctl -u launchkit-worker` on the worker host                               |
| Operations reported as indeterminate after a host failover                                      | The new host has no journaled outcome for re-delivered operations (safety behavior, not a bug)      | Expected once per failover; keep the journal on persistent storage so same-host restarts recover cleanly                  |

## Direct mode

| Symptom                                                         | Likely cause                                                                         | Fix                                                                                                     |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| Runtime stuck in `needs_credentials`                            | No API key entered yet                                                               | Hand the key to your LaunchKit contact for entry                                                        |
| Runtime flips to `error` after working                          | Plane unreachable from the LaunchKit cloud, or the key was rotated on the plane side | Check plane availability and IP allowlists; if the key changed, have it re-entered and the probe re-run |
| Probe fails with an authentication error on a CubeSandbox plane | Key validation enabled against a non-E2B key format                                  | Have key validation disabled on the runtime (see [Compatibility](/en/runtimes/compatibility))           |

## Still stuck

Send your LaunchKit contact the full `doctor` output and, for daemon issues, the last lines of `journalctl -u launchkit-worker`. Neither contains your plane's API key.