# Troubleshooting (https://tenki.cloud/docs/sandbox/troubleshooting)

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

Diagnose common Tenki 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
tenki 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
tenki sandbox create --snapshot <snapshot-id> --volume <volume-id>:/workspace/cache
```

Or after the session is up:

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

## SSH fails

Check:

* the session still exists and is `RUNNING` (`tenki 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 `tenki 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
tenki 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 `tenki sandbox exec ... -c 'ss -tlnp'`.
2. **The right port is exposed.** `tenki sandbox ports --session <session-id>` lists the active set.
3. **Inbound is allowed.** Inbound is enabled by default; exposure is rejected only if the session was created with `--allow-inbound=false` (`allowInbound: false`). `tenki sandbox get --session <session-id>` reports `allow_inbound` — as do the SDKs, via [the accessors listed here](https://tenki.cloud/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 `expose`.

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

Every SDK and the CLI enable outbound networking at create time, so a fresh session reaches the internet without any extra flag or option. Check what the guest itself sees before digging into the tool:

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

A `200` means egress is working and the failure is in the package manager, not the network. 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)

`tenki sandbox get --session <session-id>` reports the `allow_outbound` value the session was created with,
and the SDKs expose the same value — see [Port exposure and networking](https://tenki.cloud/docs/sandbox/sessions.md#port-exposure-and-networking).

## Command execution times out

Increase the timeout:

```bash
tenki 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, run it in the background inside the guest (`nohup ... &` or a systemd unit if your base image provides one) and poll for completion with subsequent exec calls.

## 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` (`tenki sandbox exec -c '...'`). To pass flags straight to a specific program, put them after `--` so the CLI stops parsing its own flags (`tenki 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
tenki sandbox exec -c 'python3 -m http.server 3000 >/tmp/server.log 2>&1 </dev/null &'
```

`exec` returns as soon as the foreground shell exits, and the server keeps running. Then `tenki sandbox expose --port 3000`.

## 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
tenki sandbox volume create ... --size 1024

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

## Still stuck?

Email us at [hello@tenki.cloud](mailto:hello@tenki.cloud) 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.