Troubleshooting
What every devbox state and error code means, and the fix for each one.
Every devbox failure comes with a code, a message, and a hint that names the fix. This page is the long version of those hints.
States
| State | Meaning |
|---|---|
creating | The machine is coming up. |
empty | Up and healthy, with nothing deployed yet. This is ready, not stuck — deploy a branch. |
building | A deploy is installing dependencies or building images. |
starting | The stack is booting; Sokko is waiting for the port to answer. |
running | The preview URL is serving your app. |
recovering | The machine restarted and the last working stack is coming back. |
degraded | Something is up but unhealthy. Check the error. |
failed | The last deploy failed. Check the error. |
stopped | Idle-stopped. Data is kept; the next deploy resumes it. |
expired | The lifetime ran out. Extend it, or create a new one. |
destroyed | Gone, permanently. |
Before the deploy starts
These are refused immediately, before anything is built.
| Code | What happened | Fix |
|---|---|---|
REPO_NOT_ACCESSIBLE | Sokko cannot read the repo | Add it to your GitHub App installation under Settings → GitHub |
REF_NOT_FOUND | That branch is not on GitHub | Push it first — Sokko deploys from GitHub, not from your agent's working copy |
COMPOSE_NOT_FOUND | Sokko could not work out how to run the repo from any source | Tell your agent the run command and port, or commit a sokko.devbox.yml |
PORT_DETECT_FAILED | No single preview port could be determined | Set expose: — a bare port in run mode, web:3000 in compose mode |
COMPOSE_INVALID | The compose file does not parse, or sets run: and compose_file: together | Fix the file; the error names the problem |
COMPOSE_UNSUPPORTED | The compose file uses a key devboxes reject | Remove the named key — see Compose stacks |
ENV_MISSING | A referenced variable has no source | Add it under Repo secrets, then redeploy |
DEPLOY_IN_FLIGHT | Another deploy is already running | Wait for it. Retrying does not queue a second one |
While it is building or starting
| Code | What happened | Fix |
|---|---|---|
BUILD_FAILED | The build, install, or the run command itself failed | Read the logs. A command not found here means the command names a tool the devbox does not have |
REGISTRY_RATE_LIMITED | Docker Hub throttled an anonymous pull | Wait for the window, or use base images from a registry that does not rate-limit |
DEPLOY_TIMEOUT | The deploy ran past its limit | Usually a server bound to localhost, or a build that is simply too slow. Check the logs |
SERVICE_UNHEALTHY | Nothing answered on the exposed port | Bind 0.0.0.0, confirm the port matches expose:, and check healthcheck_path really returns a success |
SERVICE_CRASHLOOP | The app started and kept dying | The logs carry the crash. A missing environment variable is the usual cause |
OOM | A service ran out of memory | Trim the stack, or move to a plan with a bigger devbox |
DISK_FULL | The devbox disk filled up | Destroy and recreate it, or move to a plan with more disk |
BOOT_RECOVERY_FAILED | The machine restarted and could not bring the stack back | Redeploy the branch |
Lifetime and capacity
| Code | What happened | Fix |
|---|---|---|
TTL_EXPIRED | The lifetime ran out | Extend it, or create a new devbox for the repo — its secrets are still there |
SUSPENDED_IDLE | Idle-stopped after 4 quiet hours; data is kept | Deploy again to resume it |
SUSPENDED_MID_DEPLOY | It was stopped while a deploy ran | Redeploy |
PLAN_LIMIT | Your plan has no devboxes | Devboxes start on Cookie. See Plans |
QUOTA_EXCEEDED | Every devbox slot on your plan is in use | Destroy one you are done with, or upgrade |
NO_CREDITS | The organization is out of credits | Top up in Billing |
CAPACITY_UNAVAILABLE | No room right now | Retry shortly |
TUNNEL_NOT_CONNECTED | Private mode with no connected account | Connect Tailscale under Settings → Infrastructure |
TUNNEL_UNSUPPORTED | Cloudflare Tunnel devboxes are not available yet | Use Tailscale for private, or the Sokko network |
The three problems people actually hit
The app starts but the URL shows nothing
The server bound 127.0.0.1. Almost every dev server does this by default and
it is invisible from outside. Add the host flag your framework provides
(--host 0.0.0.0, -H 0.0.0.0, --ip 0.0.0.0, -b 0.0.0.0), and make sure
its port matches expose:.
Sokko is running the wrong command
Look at what the deploy reported. If it says the command was detected, Sokko
guessed. Tell your agent the right command and port — the correction sticks to
this devbox, and once it comes up healthy it becomes your organization's saved
setup for the repo. To pin it in the repo instead, commit
sokko.devbox.yml.
A teammate cannot open the link
On the Sokko network they must sign in and be a member of your organization. In
private mode they must be on your tailnet — a .ts.net address that will not
resolve is usually a Tailscale client that is not running or is signed in to a
different tailnet.