# Troubleshooting (https://luxor.ai/docs/sandbox/troubleshooting)

> For the complete documentation index, see [llms.txt](https://luxor.ai/llms.txt)

Diagnose common Sandbox issues including session creation hangs, missing volume data after restore, SSH errors, port exposure, and command timeouts.

If something isn't working as expected, walk through the relevant section below before reaching out. Most issues come down to one of: auth, validation limits, attached resources not re-attached after restore, or the guest application itself.

## Session creation hangs or never becomes RUNNING

Check, in order:

1. **Endpoint**: is `TENKI_API_URL` (or `WithBaseURL`) pointing at the right environment?
2. **Auth token**: is `TENKI_API_KEY` set, valid, and not expired?
3. **Resource limits**: is `--cpu` between `1` and `16` and `--memory-mb` between `512` and `65536`?
4. **Snapshot**: if you passed `--snapshot`, does it have a `READY` state?

Inspect the session record directly:

```bash
luxor sandbox get --session <session-id> --json
```

## Snapshot restore works but data from a prior volume is missing

That is **expected** unless you re-attach the volume. Snapshots do not automatically restore prior volume attachments.

Re-attach explicitly:

```bash
luxor sandbox create --snapshot <snapshot-id> --volume <volume-id>:/workspace/cache
```

Or after the session is up:

```bash
luxor sandbox volume attach <session-id> <volume-id> --mount /workspace/cache
```

## SSH fails

Check:

* the session still exists and is `RUNNING` (`luxor sandbox get --session <session-id>`)
* your keys were added at create time (`--authorized-key` / `--authorized-keys-file`) or via `ssh-keys set`
* if you're using the managed SSH config, run `luxor sandbox ssh config status` to verify the assets are installed
* the session was created with inbound enabled if your environment requires it

Reset the authorized keys to a known-good set:

```bash
luxor sandbox ssh-keys set --session <session-id> --keys-file ~/.ssh/authorized_keys
```

## Port exposure fails

Check:

1. **The app is actually listening inside the guest.** Verify with `luxor sandbox exec ... -c 'ss -tlnp'`.
2. **The right port is exposed.** `luxor sandbox preview-url list --session <session-id>` lists the preview URLs bound to the session and their ports.
3. **Inbound is allowed.** Inbound is enabled by default; exposure is rejected only if the session was created with `--allow-inbound=false` (`allowInbound: false`). `luxor sandbox get --session <session-id>` reports `allow_inbound` — as do the SDKs, via [the accessors listed here](https://luxor.ai/docs/sandbox/sessions.md#port-exposure-and-networking) — and you cannot toggle it after create.

Don't hard-code preview hostnames in client code. Always use the preview URL returned by the SDK expose call, or by `luxor sandbox preview-url create` or `bind`.

## `npm install`, `pip install`, or `git clone` fails inside the guest

Every SDK and the CLI enable outbound networking by default, but workspace restrictions and session allowlists can limit destinations.
Inspect the session's network settings first:

```bash
luxor sandbox get --session <session-id> --json
```

`allow_outbound=false` blocks outbound access even when the session has an allowlist.
If `allow_domains` or `allow_cidrs` is present, check that the policy covers the failing destination, including package download hosts and redirects.
For PyPI, include `pypi.org` and `files.pythonhosted.org`; `*.pypi.org` does not include the bare `pypi.org` hostname.
Create a new session to change its allowlist or outbound setting.

Test the host used by the failing tool from inside the guest.
For npm's default registry:

```bash
luxor sandbox exec --session <session-id> -c 'curl -sS -o /dev/null -w "%{http_code}\n" https://registry.npmjs.org'
```

A `200` confirms access to this host, but other download hosts can still be blocked.
Then check:

* proxy and registry variables the session inherited from `--env` (`HTTP_PROXY`, `HTTPS_PROXY`, `NPM_CONFIG_REGISTRY`, `PIP_INDEX_URL`)
* the tool's own verbose output (`npm install --verbose`, `pip install -v`, `GIT_TRACE=1 git clone ...`)
* for private registries and private repos, whether the session has the credentials it needs (`--env`, or `githubToken` / `github_token` alongside `cloneRepoUrl` in the SDKs)

If the CLI rejects `--allow-domain` or `--allow-cidr`, upgrade to the `luxor` CLI **1.7.0 or later**.
For unrecognized SDK allowlist options, upgrade the TypeScript, Python, or Go SDK to **1.1.0 or later**.

If create fails with `session egress policy is not enabled for this workspace`, contact support to request enablement.
An `invalid_argument` error can indicate an invalid hostname, CIDR, or list size.
See [Outbound allowlists](https://luxor.ai/docs/sandbox/sessions.md#outbound-allowlists) for limits, accepted formats, and SDK policy accessors.

## `file too large for ReadFile` or `WriteFile`

A single non-streaming read or write handles at most 32 MiB. Larger calls fail with:

```text
file too large for ReadFile: size_bytes=<n> max_bytes=<m>; use ReadFileStream
```

Use the streaming calls (`readFileStream`, `read_stream`, `ReadFileStream`, and the matching write calls) or the `luxor` CLI 2.10.0 or later, which streams. See [File operations](https://luxor.ai/docs/sandbox/sessions.md#file-operations).

## `luxor sandbox read` stops early

The command prints where it stopped:

```text
read stopped at byte 524288000 of 1181116006; rerun with --offset 524288000 and the same --out to append the rest
```

Rerun with that `--offset` and the same `--out`. The file must be exactly `--offset` bytes long for the append to work.

## The sandbox was terminated and I need its files

If Luxor Agent Cloud terminated the sandbox, it usually kept the disk for 7 days. Run `luxor sandbox recover <session-id> --start` (the `luxor` CLI 2.10.0 or later). A sandbox you terminated yourself keeps nothing. See [Recover a terminated sandbox](https://luxor.ai/docs/sandbox/sessions.md#recover-a-terminated-sandbox).

Commands cut off by a termination report `session_terminated:<cause>`. See [When a sandbox stops responding](https://luxor.ai/docs/sandbox/sessions.md#when-a-sandbox-stops-responding) for the causes.

## Preview URL returns `503`

`proxy capacity exhausted: <limit>` means the edge hit the named limit. Wait a second and retry; the response carries `Retry-After: 1`. `proxy capacity exhausted: requests_per_route` or `preview connection limit reached: per_port` can mean the port already has 256 open connections. Close idle connections. See [Preview capacity errors](https://luxor.ai/docs/sandbox/sessions.md#preview-capacity-errors).

## Outbound connections fail with a 503 or an internal error

A sandbox with a domain allowlist can hold 1024 concurrent outbound connections on ports 80 and 443. Past that, port 80 gets `egress connection limit reached: session_conn_cap, 1024 per sandbox`, and TLS clients see an internal error alert such as `TLSV1_ALERT_INTERNAL_ERROR`. Reuse or close connections. See [Egress connection limit](https://luxor.ai/docs/sandbox/sessions.md#egress-connection-limit).

## Requests to `169.254.169.254` fail immediately

Sandboxes cannot reach link-local addresses, including cloud metadata services, so the connection is refused at once. This is intended. See [Link-local addresses](https://luxor.ai/docs/sandbox/sessions.md#link-local-addresses).

## An allowed domain is still blocked

`*.example.com` matches one label, so `a.b.example.com` and `example.com` do not match. Use `**.example.com` for any depth, and list the bare domain separately. See [Policy rules](https://luxor.ai/docs/sandbox/sessions.md#policy-rules).

## A restore returned `RESTORE_SECRETS_SKIPPED`

The restore left out a secret that no longer exists. See [Secrets and snapshots](https://luxor.ai/docs/sandbox/secrets.md#secrets-and-snapshots).

## API requests return `401` after a workspace was deleted

A deleted workspace's API keys stop working. Create a key in a workspace that still exists. See [What happens when you delete a workspace](https://luxor.ai/docs/account/members-and-settings.md#what-happens-when-you-delete-a-workspace).

## Command execution times out

Increase the timeout:

```bash
luxor sandbox exec --session <session-id> --timeout 5m -c 'long-running-command'
```

```go
result, err := session.Exec(
  ctx,
  "bash",
  tenkisandbox.WithArgs("-lc", "long-running-command"),
  tenkisandbox.WithTimeout(5*time.Minute),
)
```

If you need to keep running an unbounded process, start it from a template start command (`--start-cmd`) and poll for completion with subsequent exec calls. Backgrounding it over exec works for ad-hoc runs, but does not survive a guest-agent restart — see [`exec` hangs when starting a background server](#exec-hangs-when-starting-a-background-server).

## `exec` reports `flag provided but not defined: -lc`

`exec` parses its own flags first, so `-lc` is read as a CLI flag rather than a shell argument. To run a shell one-liner, use `-c` (`luxor sandbox exec -c '...'`). To pass flags straight to a specific program, put them after `--` so the CLI stops parsing its own flags (`luxor sandbox exec -- bash -lc '...'`).

## `exec` hangs when starting a background server

`exec` streams the command's stdout and stderr until they close. A process backgrounded with a bare `&` still holds those streams open, so `exec` waits for it forever (for example `python3 -m http.server 3000 &` never returns).

Redirect the background process's output and detach its stdin so it no longer holds the stream:

```bash
luxor sandbox exec -c 'python3 -m http.server 3000 >/home/tenki/server.log 2>&1 </dev/null &'
```

`exec` returns as soon as the foreground shell exits, and the server keeps running. Then `luxor sandbox preview-url create --slug my-app --session <session-id> --port 3000`.
Use `/home/tenki` or an attached volume for logs you want to keep. `/tmp` is cleared when you create a snapshot.

A process started this way is not durable. It runs inside the guest-agent's own cgroup, so a guest-agent restart kills it, and `nohup` does not change that — it blocks `SIGHUP`, which is not the signal involved. Pause and resume restore VM memory, so such a process does survive a pause with the same PID, which makes it look more durable than it is. For anything load-bearing, use a template start command (`--start-cmd`) with a readiness probe.

## Auth errors

| Symptom               | Likely cause                                          |
| --------------------- | ----------------------------------------------------- |
| `ErrUnauthorized`     | missing or malformed token; API keys start with `tk_` |
| `ErrPermissionDenied` | token authenticates but lacks the required scope      |
| `ErrRateLimited`      | back off and retry with jitter                        |
| `ErrQuotaExceeded`    | workspace has hit a resource quota; contact us        |

## Volume errors

| Symptom                  | Likely cause                                        |
| ------------------------ | --------------------------------------------------- |
| `ErrVolumeNotFound`      | wrong workspace, or volume was deleted              |
| `ErrVolumeInUse`         | volume is attached to another session; detach first |
| `ErrVolumeLimitExceeded` | workspace volume quota; delete unused volumes       |

CLI rejects bare numeric sizes:

```bash
# rejected
luxor sandbox volume create ... --size 1024

# accepted
luxor sandbox volume create ... --size 10GB
luxor sandbox volume create ... --size 10GiB
```

## Still stuck?

Email us at [hello@luxor.ai](mailto:hello@luxor.ai) with:

* the session or snapshot ID
* the CLI command or SDK call you ran
* the full error message
* the time of the failure

> **Don't paste API keys:** When sharing logs or commands with support, scrub `TENKI_API_KEY` and any `tk_` tokens. Replace and revoke the key from the API Keys screen if it ever leaves your machine.