Troubleshooting¶
Diagnosis by symptom, for when you do not already have an SBX_E code to look up. If
you do have one, go straight to the error reference — every code has
a page, and every exception already carries the fix in its hint.
Before anything else:
sandboxio doctor # what is installed, reachable and missing, with a fix per line
sandboxio doctor --json # the same, paste-friendly; prints credential names, never values
doctor exits 0 when every installed backend is healthy. It makes no provider API call,
so it costs nothing to run twice.
Symptom index¶
| What you saw | Go to |
|---|---|
ModuleNotFoundError, or an error naming an extra you have not installed |
Nothing is installed yet |
cannot reach the Docker daemon |
Docker is not reachable |
| Code inside the sandbox cannot resolve a hostname or connect | The sandbox has no network — by design |
| The command clearly failed, but no exception was raised | A failed command is not an exception |
| A call raised after roughly 300 seconds | Three different timeouts |
except TimeoutError: did not catch a sandbox timeout |
Three different timeouts |
CapabilityNotSupported, for a call that works on another backend |
The backend refuses instead of pretending |
ConfigurationError about Resources(...) |
The backend refuses instead of pretending |
| Containers still on the host after the process exited | Sandboxes that outlived the process |
OrphanedSandboxWarning |
Sandboxes that outlived the process |
UnverifiedIsolationWarning, or create() refusing a tier |
Isolation warnings and refusals |
AuthError, RateLimitError |
Provider credentials |
| A secret you passed is not visible inside the sandbox | Secrets are not env |
| A test passes but nothing actually ran | The fake executes nothing |
Nothing is installed yet¶
The core package contains no backend. Two different errors say so:
| Code | Means | Fix |
|---|---|---|
SBX_E1002 BackendNotInstalled |
a first-party backend whose extra is missing | uv pip install "sandboxio[docker]" |
SBX_E1001 BackendNotFound |
no backend is registered under that name at all | check the spelling; the hint lists what is registered |
A third-party adapter is BackendNotFound rather than BackendNotInstalled — sandboxio
cannot know its install command, so the hint names what it does know.
Docker is not reachable¶
sandboxio.errors.CreationError: [SBX_E1201] cannot reach the Docker daemon
Fix: Start Docker, or set DOCKER_HOST; `sandboxio doctor` explains.
The adapter creates its client on first use, never at import, so this surfaces at
create() rather than at import sandboxio. Work through it in this order:
docker info— if that fails, this is a Docker problem, not a sandboxio one.sandboxio doctor— it reports reachability and the engine version.- A non-default socket (Colima, Rancher Desktop, a remote engine) needs
DOCKER_HOSTexported in the same shell that runs your program.
The sandbox has no network — by design¶
This is the single most common surprise, and it usually does not raise a sandboxio
error. create() denies egress by default, so the failure happens inside your code: a
DNS resolution error, a connection refused, a pip install that cannot reach PyPI. What
comes back is an ExecResult with a non-zero exit_code and the real reason in stderr.
import sandboxio
async with await sandboxio.create() as sb:
res = await sb.run(["python", "-c", "import urllib.request; urllib.request.urlopen('https://example.com')"])
print(res.exit_code, res.stderr) # non-zero, and a socket error — not an SBX code
That is the deny-by-default policy working (why). Your options, in order of preference:
- Bake the dependencies into the image, or upload an offline wheelhouse — both work under the default policy (Docker how-to).
- Allowlist the hosts you need, on a backend that can enforce one (E2B how-to). Docker cannot, and says so rather than granting full access.
- Open egress explicitly with
NetworkPolicy(egress="allow"), when the code is trusted and you have decided that is acceptable.
Two things this is not:
- Not an image-pull problem.
docker pullruns on the host daemon, outside the container's network namespace, so a deny-egress sandbox still starts from a remote image. - Not
SBX_E1401NetworkPolicyViolationin most cases. That code is raised where the backend itself reports a blocked attempt; a container withnetwork: nonehas nothing to report, because there is no network stack to block.
A failed command is not an exception¶
run() and run_code() return an ExecResult. A non-zero exit is data, not a raise —
the same shape as subprocess.run() without check=True:
import sandboxio
async with await sandboxio.create() as sb:
res = await sb.run(["pytest", "-q"])
if not res.ok: # exit_code != 0
print(res.stderr)
res.raise_for_status() # ExecutionError (SBX_E1301) with the result attached
If a step in your pipeline "silently did nothing", check res.ok first. When it did raise,
SBX_E1301 carries the whole result: exc.result.stderr and
exc.result.exit_code.
Three different timeouts¶
They look alike and have different fixes:
| Raised | Code | What ran out | Fix |
|---|---|---|---|
CreateTimeout |
SBX_E1203 |
the sandbox did not become usable in time | raise timeout= on create(), or use a warmer image/template |
ExecutionTimeout |
SBX_E1302 |
one run(), run_code() or stream |
raise timeout= on the call, or make the code finish sooner |
SandboxGone |
SBX_E1204 |
the sandbox's whole lifetime, while you were using it | raise timeout= on create() — this is the sandbox-level budget, not the call's |
SandboxGone is deliberately not a timeout subclass: the fix is a different parameter.
timeout=None on a call means inherit the sandbox timeout, never unbounded, and
timeout=None on create() is refused outright. There is no way to ask for forever.
except TimeoutError: will not catch any of these. On Python 3.11+ the builtin is what
asyncio raises, so inheriting from it would make "my deadline fired" and "the sandbox's
limit fired" indistinguishable (ADR-0017). Catch the
library's own base instead:
import sandboxio
try:
async with await sandboxio.create() as sb:
await sb.run("sleep 999", timeout=5)
except sandboxio.SandboxTimeout as exc: # CreateTimeout and ExecutionTimeout
print(exc.code, exc.hint)
The backend refuses instead of pretending¶
A backend that cannot honour a typed argument raises rather than quietly ignoring it. This is the rule that makes the defaults worth trusting, and it is also why a call that works on one backend can fail on another:
| You asked for | On | Result |
|---|---|---|
NetworkPolicy(allow=[...]) |
Docker | CapabilityNotSupported — Docker has no per-host egress filtering (ADR-0023). Allowlists are an E2B/Modal capability |
run_code(context_id=...) |
Docker | CapabilityNotSupported — STATEFUL_CODE is off for Docker in v0.1 (ADR-0024) |
Resources(disk_mb=...) |
Docker | ConfigurationError — Docker cannot cap disk; drop it or pick a backend that can |
Resources(...) |
E2B | ConfigurationError — caps belong to the template; pick a template with the resources you need |
egress="learn" |
anything | raises in v0.1 rather than degrading to deny |
Never write a try/except that swallows one of these into a fallback: the refusal is the
feature. Discover instead of guessing:
import sandboxio
from sandboxio import Capability
async with await sandboxio.create() as sb:
if Capability.STATEFUL_CODE in sb.capabilities:
await sb.run_code("x = 41", context_id="session-1")
Sandboxes that outlived the process¶
Normal teardown happens on context-manager exit, including on exception and on cancellation. What survives that is visible and removable:
sandboxio reap # lists, running and stopped — dry run by default
sandboxio reap --label tenant_id=acme # narrowed by your own metadata
sandboxio reap --kill # removes what was listed
Three ways a container is still there:
- The process crashed with the reaper disabled (
SBX_DOCKER_REAPER=0). The Ryuk-style sidecar normally removes the session's containers when the process dies. - The lifetime expired. The container's PID 1 is
sleep <timeout>; when it fires, Docker leaves the container stopped, not removed. - Teardown exceeded its grace. You will have seen
OrphanedSandboxWarningwith the id and labels — that warning exists precisely soreaphas something to go on. RaiseSBX_TEARDOWN_GRACEif a slow host makes 5 seconds too tight.
Always ran under async with, and still leaking? That is a bug worth an issue — CI asserts
zero io.sandboxio.managed containers remain after every Docker job, so a reproduction is
actionable (H2).
Isolation warnings and refusals¶
UnverifiedIsolationWarning means the backend reports UNKNOWN — its adapter has not
verified what it isolates with. It is emitted once per backend, and an UNKNOWN backend
satisfies no require_isolation= requirement at all.
create(require_isolation=...) raising ConfigurationError is the feature working: the
check runs before provisioning, so nothing was created and nothing was billed. Either
point at a backend that meets the tier, or lower the requirement deliberately —
require_isolation=UNKNOWN is meaningless and raises.
Read isolation tiers before deciding which way to go.
CONTAINER is not a boundary against hostile code.
Provider credentials¶
SBX_E1501 AuthError names the exact environment variable it
wanted — export that one, in the shell that runs your program, and re-run
sandboxio doctor to confirm it is seen. doctor reports variables by name with set/unset
and never prints a value.
SBX_E1502 RateLimitError is the provider throttling you.
sandboxio does not retry on your behalf in v0.1 — back off in your own code.
Secrets are not env¶
secrets= and env= are separate parameters on purpose. Values passed as secrets= are
redacted everywhere they could surface: messages, notes, reprs, audit events, spans and CLI
output. If you are grepping logs for a secret to confirm it arrived, you will not find it —
that is the redaction, not a delivery failure.
Credentials in a DSN are refused: the DSN carries a backend, a template and timeout, and
nothing else. Use typed configuration and the provider's environment variable
(spec/05).
The fake executes nothing¶
fake:// and the sbx_fake fixture run no code at all. A test that asserts on real output
without scripting a result first is asserting on a default, not on your logic:
import pytest
from sandboxio import ExecResult
@pytest.mark.anyio
async def test_tool(sbx_fake):
sbx_fake.on_run_code(match="import pandas", returns=ExecResult(0, "2.2.1\n", ""))
res = await sbx_fake.sandbox.run_code("import pandas; print(pandas.__version__)")
assert "2.2.1" in res.stdout
The fake reports CONTAINER while isolating nothing, because it is for tests — never use
it as a stand-in for a security boundary. More in
offline testing.
Still stuck¶
- Include
sandboxio doctor --jsonin any report; it is built for pasting and prints no secrets. - A reproducible bug goes to issues; a question goes to discussions (SUPPORT.md).
- A security vulnerability goes privately through the Security tab, never an issue (SECURITY.md).
- A default that appears to apply and does not is the highest-severity bug this project can have (H1). Report it as one.