Common Problems & Debugging

Table of Contents

1. The sandbox itself won't start
2. A container doesn't start / exits immediately
3. Port already in use
4. Network connectivity problems
5. Permission issues
6. Checking logs and processes, quickly
7. Cleaning up unused resources
8. Beginner Pitfalls

1. The sandbox itself won't start

If sbx run hangs, errors, or a sandbox refuses to come up at all, don't jump straight to deleting things. Run diagnostics first:

sbx diagnose

This checks for a missing CLI binary, daemon reachability problems, a CLI/daemon version mismatch, missing storage directories, and broken authentication — and suggests fixes.

If commands hang or keep returning daemon errors specifically, restart the sandbox daemon (this does not delete any sandbox data):

sbx daemon restart

Only if that doesn't help, and you're willing to lose all sandbox state, use the last resort:

sbx reset

2. A container doesn't start / exits immediately

Same debugging instincts as any other Docker host — you're just running them inside the sandbox:

docker ps -a
docker logs sbx-postgres

docker ps -a (not just docker ps) shows stopped and crashed containers too, with an exit code in the STATUS column. docker logs <name> almost always shows why — a missing environment variable, a port already bound, a bad config file.

3. Port already in use

This shows up two different ways, and they need different fixes:

• Inside the sandbox, docker run -p 5432:5432 fails because something else in the sandbox already bound that port. Check with docker ps for a container already using it, or just pick a different host-side port in the sandbox: -p 5433:5432.
• On your host, sbx ports sbx-crash-course --publish 3000:3000 fails because your host's port 3000 is already taken by something else on your machine. Either free it, or let sbx pick one for you:

sbx ports sbx-crash-course --publish 3000
sbx ports sbx-crash-course   # see which host port was actually assigned

4. Network connectivity problems

If a docker pull, npm install, or curl inside the sandbox times out or gets refused, it's very often the network policy from Part 2 — Balanced blocks anything not on its allowed list — not a real outage. Check what's being blocked, from your host:

sbx policy log

Then allow whatever domain your workflow actually needs:

sbx policy allow network registry.npmjs.org

Separately: if something on your host needs to be reached from inside the sandbox, plain 127.0.0.1 or your machine's LAN IP won't work — use host.docker.internal instead, and allow that specific host/port if your policy requires it (see Part 3).

5. Permission issues

The sandbox shell has sudo, so most "permission denied" errors inside it are ordinary Linux permission issues — fix them the normal way (sudo chown, sudo apt-get install, and so on), not a sandbox-specific problem.

If instead you see You are not authenticated to Docker from sbx itself, your Docker login session expired:

sbx login

6. Checking logs and processes, quickly

A short checklist, in the order it's usually worth trying:

docker ps -a              # what's running, what crashed
docker logs <container>   # why it crashed
ps aux                    # is a process even attempting to run
docker inspect <container> --format '{{.State.Status}} {{.State.ExitCode}}'

7. Cleaning up unused resources

Inside the sandbox, ordinary Docker cleanup applies:

docker system df     # see what's taking up space
docker container prune
docker image prune

On your host, sbx has its own equivalent for sandboxes themselves — remove every stopped sandbox at once (running ones are never touched):

sbx prune --dry-run   # preview first
sbx prune

8. Beginner Pitfalls

• A blocked network request and a genuinely broken connection look identical from the error message alone. Check sbx policy log before assuming something is actually down.
• sbx reset deletes all sandbox data, not just the one giving you trouble — reach for sbx daemon restart first.
• docker system df/prune only clean up inside the sandbox you run them in. They have no effect on your host or on any other sandbox.