Troubleshooting
Start with froog info NAME (state, error, auto-stop timer, disk retention) and froog status --check (sign-in and API reachability). API errors carry a code, listed here.
| Problem | What to do |
|---|---|
Permission denied (publickey) from froog ssh | Your key isn't on the sandbox. froog keys list shows your account's keys, and froog keys add ~/.ssh/id_ed25519.pub adds one. Keys are written at each start, so then froog stop NAME and froog start NAME. |
Host key verification failed from plain ssh or an editor | A hand-written ~/.ssh/config entry points at an old address or port: the sandbox started again on a new one. Replace it with froog ssh-config, whose entries look the address up at each connection. See VS Code and Cursor. |
409 conflict: the sandbox isn't running | froog start NAME. SSH, exec, files, public URLs and the desktop need a running sandbox. History and saved snapshots don't. |
The sandbox is in error | froog info NAME says why. froog restore NAME@latest brings it back from its newest snapshot. A new sandbox that never ran has no snapshot: delete it and create it again. |
| A sandbox stopped by itself | Its auto-stop timer ran out (froog info shows when, it counts from the start, not from activity: froog extend NAME --hours 8 for longer, --no-auto-stop for none), this month's charge for your setup failed, or it was the free lite and froog needed the room (froog billing says which). A sandbox.stopped webhook tells you when it happens. |
sandbox.degraded, or programs ended without a stop | The machine under the sandbox restarted or its VM stopped, and froog started it again. The disk is intact, but processes ended. Run long-lived services from the setup script so they come back. |
402 capacity_full · 402 card_required | Your setup has no free slot of that size and kind of vCPUs: stop one, or add one (froog billing capacity default=2, the message says which). For the free lite, add a card (froog billing card). |
402 capacity_unpaid | This month's charge for your setup failed: pay it on a Stripe page (Pay now on the Billing page, POST /v1/billing/capacity/pay) or add another card (froog billing card; it's charged at once); it's also tried again every hour. |
402 authentication_required | Your card's bank asks you to confirm each payment, which froog can't do for you: pay on the Stripe page the error links to, or use another card. |
402 insufficient_balance · 402 spend_cap_reached | A Pushbox CI runner needs an hour of job time in the wallet (froog wallet pay 20), or this month's wallet usage reached your cap (froog billing cap 100 or off). |
402 credit_required | You keep all 10 included saved snapshots and the wallet is empty: add money (froog wallet pay 20) or remove a saved snapshot (froog snapshots --rm NAME). |
404 org_not_found · 403 org_role_forbidden · 403 sandbox_private | The request named an organization you aren't in (froog org list), your role can't do this (ask an owner or admin), or the sandbox is a teammate's private one. A sandbox you can't find may be in another workspace: froog org shows the one in scope. |
429 member_limit_reached · 402 team_member_cap_reached | Your organization capped you: stop one of your organization sandboxes, or ask an owner or admin to raise the cap (froog org cap). |
429 limit_reached | The message names the limit: sandboxes at once (stop one, or add money for the next tier), starts per minute, hour or day (wait), or froog being at capacity (try again in a few minutes). froog limits shows where you are. |
snapshot_data_expired | The sandbox stayed stopped over 14 days and its disk was deleted. froog restore NAME@SNAPSHOT from a saved snapshot, if you have one, or delete it. |
fast_mode_not_supported | That harness or model has no fast mode. froog prompt --list-models lists the ones that do. |
no_running_turn | A steer with nothing running in the conversation. Send a prompt instead. |
provider_not_configured (exit code 78) | The agent has no key or login in that sandbox. froog env set ANTHROPIC_API_KEY (or the harness's key, see Coding agents) and start the sandbox again, or log in inside it. |
| A variable, secret file or repo is missing | Environment changes reach a sandbox at its next start, and --no-environment sandboxes (and their forks) get none. Variables are loaded by login shells, froog exec, background commands and prompts: elsewhere, run set -a; . ~/.froog/env; set +a. |
| The setup script or a clone failed | froog jobs NAME lists the setup job, and froog logs NAME JOB prints its output. Private repos need GH_TOKEN or a .git-credentials secret file. |
| A public URL doesn't answer | The service must listen on that port inside the sandbox (localhost is fine): check with froog exec NAME -- 'ss -ltn'. The first visit to a new URL takes a few seconds while its certificate is issued. A private URL in an iframe on another site can stay blank: use --public. |
| Can't connect to a private IP, or to port 25 | Both are blocked from sandboxes. See Network. |
A stop was refused (stop_refused_at in its info) | Its snapshot failed, usually because the disk is full: check with froog exec NAME -- df -h / and free space. froog retries the stop by itself. froog stop NAME --force stops it now with its last good snapshot. froog start NAME cancels the stop. See Stopping safely. |
| A command exited with 137 | It was killed with SIGKILL. With oom_killed: true it ran out of memory: use less, or a larger size (froog stop NAME && froog start NAME --size large). |
A sandbox isn't answering (unresponsive_since in its info) | Wait a few minutes: after a crash it restarts by itself. Then froog stop NAME --force && froog start NAME (you lose what was written after its last snapshot). If it never had a snapshot, don't stop it: email us. See Not answering. |
A sandbox is in error | Read why with froog info NAME. froog rebuilds one whose VM was lost from its last snapshot by itself. Otherwise froog start NAME retries from it. See Errored sandboxes. |
| An email says the disk is 85% or 95% full | Find what's big with froog exec NAME -- 'sudo du -xh / 2>/dev/null | sort -h | tail -n 20' and delete it, or move to a larger size. See Disk space. |
| A desktop link doesn't open | Links must be opened within 10 minutes and stop working when the sandbox stops: run froog desktop NAME again. |
500 internal with (ref …) | Something failed on froog's side. Send the ref with froog feedback "…" or to hello@froog.tech. |