Troubleshooting
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:
- Endpoint: is
TENKI_API_URL(orWithBaseURL) pointing at the right environment? - Auth token: is
TENKI_API_KEYset, valid, and not expired? - Resource limits: is
--cpubetween1and16and--memory-mbbetween512and65536? - Snapshot: if you passed
--snapshot, does it have aREADYstate?
Inspect the session record directly:
luxor sandbox get --session <session-id> --jsonSnapshot 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:
luxor sandbox create --snapshot <snapshot-id> --volume <volume-id>:/workspace/cacheOr after the session is up:
luxor sandbox volume attach <session-id> <volume-id> --mount /workspace/cacheSSH 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 viassh-keys set - if you're using the managed SSH config, run
luxor sandbox ssh config statusto 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:
luxor sandbox ssh-keys set --session <session-id> --keys-file ~/.ssh/authorized_keysPort exposure fails
Check:
- The app is actually listening inside the guest. Verify with
luxor sandbox exec ... -c 'ss -tlnp'. - The right port is exposed.
luxor sandbox preview-url list --session <session-id>lists the preview URLs bound to the session and their ports. - 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>reportsallow_inbound— as do the SDKs, via the accessors listed here — 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:
luxor sandbox get --session <session-id> --jsonallow_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:
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, orgithubToken/github_tokenalongsidecloneRepoUrlin 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 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:
file too large for ReadFile: size_bytes=<n> max_bytes=<m>; use ReadFileStreamUse 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.
luxor sandbox read stops early
The command prints where it stopped:
read stopped at byte 524288000 of 1181116006; rerun with --offset 524288000 and the same --out to append the restRerun 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.
Commands cut off by a termination report session_terminated:<cause>. See 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.
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.
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.
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.
A restore returned RESTORE_SECRETS_SKIPPED
The restore left out a secret that no longer exists. See 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.
Command execution times out
Increase the timeout:
luxor sandbox exec --session <session-id> --timeout 5m -c 'long-running-command'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 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:
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
Volume errors
CLI rejects bare numeric sizes:
# rejected
luxor sandbox volume create ... --size 1024
# accepted
luxor sandbox volume create ... --size 10GB
luxor sandbox volume create ... --size 10GiBStill stuck?
Email us at 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.