# Troubleshooting

> Common Flax Cloud errors and how to fix API keys, quota failures, capacity responses, previews, browser CDP URLs, files, and cleanup.

Most Flax Cloud failures include a stable error `code`. Match on that code, not the exact human
message. Every API error has this shape:

```json
{ "error": { "code": "memory_limit", "message": "..." } }
```

## Authentication

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `401 missing_credentials` | No dashboard session or API key was sent. | Set `FLAX_API_KEY`, pass `Authorization: Bearer ...`, or sign in again. |
| `401 invalid_api_key` | The key is mistyped, revoked, or from another environment. | Create a fresh key in **API Keys** and update your secret store. |
| CLI says "not logged in" | No saved key and no `FLAX_API_KEY`. | Run `flax login` or export `FLAX_API_KEY=flax_live_...`. |

SDKs also support `FLAX_BASE_URL` for local/self-hosted testing. Leave it unset for production.

## Quotas and capacity

| Code | Meaning | Fix |
|------|---------|-----|
| `memory_limit` | Requested sandbox memory is above your plan. Free is 1 GB, Pro is 2 GB, Builder is 4 GB, Team is 8 GB. | Choose a smaller memory size or upgrade. |
| `concurrency_limit` | You already have the plan's maximum live sandboxes. | Stop or destroy a sandbox, then retry. |
| `runtime_limit` | Monthly active runtime minutes are exhausted. | Wait for reset or upgrade. |
| `storage_limit` | The sandbox workspace is above its storage cap. | Delete files under `/workspace` or upgrade. |
| `daily_sandbox_limit` | Too many sandbox creates in a rolling 24h window. | Wait before creating more sandboxes. |
| `capacity_unavailable` | The worker fleet is full right now. | Retry after a sandbox stops. If you see this often, upgrade capacity or contact support. |
| `server_busy` | The API is temporarily saturated. | Honor `Retry-After` and retry. |

## Sandboxes and cleanup

- **Stop** keeps the sandbox record and archives the workspace so it can be resumed.
- **Destroy** is permanent. Files, preview links, browser sessions, and the sandbox id are removed.
- Stopped sandboxes have a retention window based on plan. Resume or snapshot important work before
  that window expires.
- If a sandbox is stuck in `creating` or `failed`, destroy it and create a new one. If it repeats,
  include the sandbox id when contacting support.

## Files

Files should live under `/workspace`. If a command cannot see a file:

1. Confirm you uploaded to an absolute path like `/workspace/app.py`.
2. List the directory with the SDK, CLI, or `ls /workspace` inside the sandbox.
3. If you destroy the sandbox, files are gone. Use stop/resume or snapshots for persistence.

## Previews

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `502 preview_unreachable` | Nothing is listening on the requested port, or the server bound to `127.0.0.1`. | Start the server with `--bind 0.0.0.0` or equivalent. |
| `409 preview_unavailable` | The sandbox has `network_mode: "none"`. | Recreate with the default `bridge` network. |
| Shareable link returns `404` | The link was disabled, rotated, unknown, or the sandbox is stopped/destroyed. | Create a new link and keep the sandbox live. |
| App redirects look wrong under private preview | Private previews run under `/v1/sandboxes/.../preview/{port}/`. | Use a shareable preview link for root-path apps. |

Use a startup command for web servers that should come back after stop/resume:

```bash
flax startup "$SID" --set "python3 -m http.server 8000 --bind 0.0.0.0" --run
flax preview "$SID" 8000
```

## Browser and CDP

- CDP URLs are short-lived secrets. Mint a new URL for each automation run.
- Anyone holding a CDP URL can control that browser until it expires, so keep it server-side.
- Browser sandboxes need network access and enough memory headroom for Chromium.
- Browser state lives under `/workspace/.flax/browser/`. Snapshots and forks copy those files, but
  they do not preserve a live Chromium process.

## Getting help

Send the error code, sandbox id (`sbx_...`), command id (`cmd_...`) if relevant, and what you were
trying to do to [hi@flaxcloud.com](mailto:hi@flaxcloud.com). Report security issues privately to
[security@flaxcloud.com](mailto:security@flaxcloud.com).