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), the 24-hour grace period after plan usage and the wallet ran out ended (or passed its debt cap), or the free trial's 25 hours were used up. 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 subscription_required · 402 insufficient_funds | Choose a plan (froog billing plan 20) · this period's plan usage and the wallet are used up: froog wallet pay 15, or froog wallet auto 20 for auto top-up. |
429 trial_compute_limit_reached | The free trial's 25 hours are used: froog billing end-trial starts the plan now. |
403 trial_auto_stop_required | The free trial needs an auto-stop timer of 2 hours or less: --ttl 2h (or less), not --no-auto-stop. The paid plan allows up to 30 days, or none. |
402 credit_required | You keep all the saved snapshots your plan includes and the wallet is empty: add money (froog wallet pay 15) or remove a saved snapshot (froog snapshots --rm NAME). |
403 trial_no_saved_snapshots | The free trial can't save new saved snapshots. The ones you have stay. froog billing end-trial starts the plan now. |
403 plan_by_request | Plans above $100 a month are by request: email hello@froog.tech. |
402 trial_blocked | The card already had a free trial on another account, so this account's plan starts paid and its charge didn't go through: froog billing end-trial (or update the card with froog billing portal). |
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 ask for more), 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. |