Troubleshooting

Common symptoms and what to do about them. Every SDK method throws on a non-2xx response, and the error message includes the HTTP status plus the first 200 bytes of the response body, so the status code below is usually visible in the thrown error.

401 Unauthorized

Your API key is missing, malformed, or revoked.

What to do:

• Confirm ISORUN_API_KEY is set in the environment the SDK runs in (echo $ISORUN_API_KEY).
• Check the key still exists in the dashboard. Revoked keys stop working immediately.
• Use the full key, including its region segment. The SDK derives the endpoint from it, so a truncated or edited key won't route.

429 Too Many Requests

You've hit a rate or capacity limit.

What to do:

• Back off and retry, transient capacity limits clear quickly.
• Destroy sandboxes you're no longer using; concurrent sandboxes count against your limits.
• If you're launching a burst, stagger creates rather than firing them all at once.

My command times out

exec has a default timeout of 30 seconds.

What to do:

• Pass a longer timeout: sandbox.exec('pytest -q', 180).
• For long-running builds, tests, or training, use execStream so you get incremental output instead of waiting for a single buffered result.

The sandbox disappeared on its own

Sandboxes auto-destroy when their timeoutSec idle timer fires.

What to do:

• Set a longer timeoutSec at create time.
• Call sandbox.setTimeout(seconds) to extend the timer when you hand the sandbox to a long-running workflow.

My public URL doesn't respond

A public URL is anonymous: the unguessable run ID in the host is the credential, so a missing header isn't the cause.

What to do:

• Confirm the sandbox is still alive (not destroyed or past its timeoutSec) and your service is listening on that port. Localhost-only servers are exposed automatically; the first hit to a new port can be slightly slower.
• Treat the URL as a secret. If it leaked, destroy the sandbox.

The first boot of an image is slow

The first time a runner sees an image, it pulls and prepares it. Every boot after that is instant.

What to do:

• Pin a real tag or digest, latest and lts are rejected at create time.
• Warm the image once at startup if your first request is latency-sensitive.

Outbound connections drop after resume

Hibernate preserves filesystem, memory, and processes, but established outbound TCP connections don't survive.

What to do:

• Re-open connections (DB clients, websockets, streams) after resume().

My code can't reach the internet

Egress is filtered at the host. If a sandbox uses a locked-down network profile, outbound traffic to unlisted hosts is dropped.

What to do:

• Pick or author a network profile that allows the hosts you need.
• Use credential injection for third-party APIs so the key never enters the guest.

Next steps

• Network profiles, control egress per sandbox.
• Lifecycle, how hibernate, resume, and timeouts work.
• TypeScript SDK reference, method signatures and errors.