# 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 [#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 `128` 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 [#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 [#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 [#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.** The session must have been created with `--allow-inbound`. You cannot toggle inbound after create.

Don't hard-code preview hostnames in client code. Always use the `preview_url` returned by `expose`.

Command execution times out [#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-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-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 [#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 [#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? [#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.