Troubleshooting

Start with boat info <id>. It shows the state, the auto-stop time (archiveAfter), the reason for a stop or a failure (error), and the time of the last snapshot (snapshotCompletedAt).

boat info bx_f7k2q9hd

Why did my sandbox stop?

Auto-stop is the most common cause. A stop by Boat keeps the disk, the same as boat stop, unless the table says otherwise.

Cause	How to check	Data
Auto-stop. The default is 1 hour, counted from the create or the last resume. A running prompt moves the time later	`archiveAfter` in `boat info` is in the past	Kept
Empty balance for 24 hours. Boat sends an email when the balance runs out, then stops your sandboxes 24 hours later	`boat billing status`. Email “Balance ran out”	Kept
Plan cancelled with no credit left. The stop comes at once, with no 24-hour wait	`boat billing status`	Kept
Free trial used its 25 hours of compute	`boat billing status`. New starts fail with `trial_compute_limit_reached`	Kept. Read Free trial
Forced stop after 3 days of failed saves. A stop was refused because its snapshot kept failing	Email “could not be stopped”	Kept up to the last good snapshot. Later writes are lost
Machine stopped answering for 3 days, with no snapshot newer than the failure	Email about a sandbox that stopped responding	Kept up to the last good snapshot. Later writes are lost
Account closed	Email that confirms the closing	Kept for 30 days. Read Close your account

Two settings change what a stop keeps:

Setting	How to check	Data
Zero data retention	`boat data-retention status`	Deleted at the stop. You cannot resume
Snapshots off	`"snapshots": false` in `boat info`	Erased at the stop. You cannot resume

To get the sandbox back, run boat resume <id>.

Boat keeps the disk of a stopped sandbox for 14 days only. On day 14, it deletes the data, whatever the cause of the stop. Read Keep a stopped sandbox longer than 14 days.

To stop auto-stop for a long job:

boat extend bx_f7k2q9hd --hours 12     # sets the auto-stop to 12 hours from now
boat extend bx_f7k2q9hd --no-auto-stop # runs until you stop it

Read Auto-stop. To never stop for an empty balance, turn on Auto-refill on the Billing tab.

A sandbox does not answer

If commands and SSH hang, Boat marks the sandbox as not answering. Boat sends you an email. Billing pauses while it does not answer. The disk stays on the machine. Do these steps in this order:

Wait a few minutes. A sandbox that answers again reconnects by itself, with all its data.
Run boat recover <id>. This restarts the machine. The disk is not touched. It usually answers again in 1 to 2 minutes, then saves your work by itself.
If recover does not help, run boat resume <id>. The sandbox comes back from its last snapshot. You lose what was written after that snapshot. snapshotCompletedAt in boat info shows its time.
If the sandbox never completed a snapshot, do not resume. Contact us. We get the disk back by hand.

boat recover bx_f7k2q9hd

You can also choose Recover in the ⋯ menu of the sandbox in the dashboard. After 3 days without an answer, Boat stops the sandbox. It falls back to its last snapshot. Boat sends a reminder one day before.

”This sandbox is responding normally, so there is nothing to recover.”

recover works only on a sandbox that does not answer or is in error. To get a fresh machine for a sandbox that answers, run boat stop, then boat resume.

”Recovery already started. Give it N more minute(s) before trying again.”

Boat allows one recover each 10 minutes. A restart takes 1 to 2 minutes. Wait, then check with boat info.

”This sandbox runs on a machine that cannot be power-cycled.”

Some machines cannot restart on request. Wait for the sandbox to answer again, or resume it from its last snapshot.

A sandbox is in error

error means that Boat lost contact with the machine, or that a start failed. boat info shows the reason in error.

Question	Answer
Am I billed?	No. Billing stops while the sandbox is in `error`
Is my data safe?	Boat keeps the machine and its disk for 3 days. Everything up to the last snapshot is safe in any case
Does Boat fix it by itself?	Sometimes. If the last snapshot is newer than the failure, Boat rebuilds the sandbox on a new machine from that snapshot and sends you an email
Can I run commands?	No. Commands fail with `409 sandbox_not_ready`

Do these steps in this order:

Read the reason: boat info <id>. Check your email from Boat.
Run boat recover <id>. Wait 2 minutes.
If it is still in error, run boat resume <id>. You lose what was written after snapshotCompletedAt.
If you cannot lose that work, do not resume. Contact us within 3 days.

After 3 days, Boat stops the sandbox. It falls back to its last snapshot. To stop an errored sandbox without a resume, run boat stop <id>. To erase it, read Delete a sandbox.

A command was killed: exit code 137 (out of memory)

Your programs can use all the RAM of the size except 512 MiB. Boat keeps that part for its own services. Above that limit, Linux kills the process that uses the most memory. The sandbox stays up.

The killed command ends with exitCode 137, and the command result shows oomKilled: true.
Other processes and the sandbox keep running.
Use less memory, or move to a bigger size. Read Change size.

boat stop bx_f7k2q9hd
until [ "$(boat info bx_f7k2q9hd --json | jq -r .sandbox.state)" = "stopped" ]; do sleep 2; done
boat resume bx_f7k2q9hd --type large

Out-of-disk emails

Boat reads the disk use of each running sandbox and emails you:

Disk use	Email
85%	A warning. Free space before the disk fills.
95%	“Out of disk”. Snapshots fail, so your newest work is not saved. A stop also fails.

You get at most one email per level per day for each sandbox. When space gets low, Boat deletes caches that it can download again: the apt cache, journal logs and pulled Docker images that no container uses. Boat never deletes your own files. To free space:

boat ssh bx_f7k2q9hd
docker system prune      # unused Docker data
sudo apt-get clean       # apt download cache

If the sandbox needs more disk, stop it and resume it with a bigger --type. If you cannot get in, contact us. Do not resume from an old snapshot if you need the unsaved work.

A stop does not finish

A stop saves the disk first. If the save fails, Boat refuses the stop, keeps the sandbox running and does not bill you while it waits. Read When a stop is refused. boat stop returns at stopping. A short stopping is normal. To wait for stopped, read Wait for the stop in a script.

Error messages

`409 snapshot_data_expired`

This sandbox's data was deleted 14 days after it stopped. Save a named snapshot to keep data: boat snapshot <id> <name>.

The sandbox stayed stopped for 14 days, and Boat deleted its data. Resume, fork and a named snapshot save of this sandbox fail. You cannot get the data back. The sandbox stays in your list until you delete it. Next time, save a named snapshot before day 14. Boat emails you on day 11. Read Keep a stopped sandbox longer than 14 days.

`409 sandbox_starting`

Sandbox is still starting (current state: provisioned); environment and secrets are not applied yet. Retry when the sandbox is ready.

The API held your command for 60 seconds, and the sandbox was still starting. Send the command again. Read Readiness and resume speed.

`409 sandbox_not_ready`

Sandbox is not ready (state: archived). Resume or recover it before running commands.

The sandbox is stopped or in error. Run boat resume <id>. For error, read A sandbox is in error.

`409 machine_not_running`

Sandbox machine is not running.

The sandbox has no machine now. It is stopped, or it waits for a machine. Run boat info <id> and resume it if it is stopped.

`409 sandbox_stopping`

Sandbox is still stopping and would resume on its live machine, which cannot switch environment.

A resume during stopping keeps the same machine, so it cannot change the environment. Wait for stopped, then resume with --environment.

`429 rate_limited`

Rate limit hit: 12 sandbox starts per minute (create, fork and resume each count as one start).

You started more sandboxes than your plan allows in that window. Wait, then start again. Read Limits and errors.

`429 trial_compute_limit_reached`

Trial Sandbox compute is limited to 25 hours total. Stopping, forking, or resuming does not reset that allowance.

The free trial used its 25 hours. The first payment removes this limit. Read Free trial.

`503 no_ready_machine`

You sent failFast and no machine of that size was free. Nothing was created or billed. Retry, or fall back to another size. Read Fail fast when no machine is free.

`402 credit_required`

You keep 10 or more named snapshots, and you saved one more without credit. Add funds, or remove a named snapshot. Read Named snapshot pricing.

Get started

Use cases

Connect to a sandbox

Run work and keep it running

Set up new sandboxes

Stop, resume and snapshots

Machines

Run agents inside

Teams

Security, isolation, data & compliance

Help

Troubleshooting

Why did my sandbox stop?

A sandbox does not answer

”This sandbox is responding normally, so there is nothing to recover.”

”Recovery already started. Give it N more minute(s) before trying again.”

”This sandbox runs on a machine that cannot be power-cycled.”

A sandbox is in error

A command was killed: exit code 137 (out of memory)

Out-of-disk emails

A stop does not finish

Error messages

`409 snapshot_data_expired`

`409 sandbox_starting`

`409 sandbox_not_ready`

`409 machine_not_running`

`409 sandbox_stopping`

`429 rate_limited`

`429 trial_compute_limit_reached`

`503 no_ready_machine`

`402 credit_required`

Still stuck

​Why did my sandbox stop?

​A sandbox does not answer

​”This sandbox is responding normally, so there is nothing to recover.”

​”Recovery already started. Give it N more minute(s) before trying again.”

​”This sandbox runs on a machine that cannot be power-cycled.”

​A sandbox is in error

​A command was killed: exit code 137 (out of memory)

​Out-of-disk emails

​A stop does not finish

​Error messages

​409 snapshot_data_expired

​409 sandbox_starting

​409 sandbox_not_ready

​409 machine_not_running

​409 sandbox_stopping

​429 rate_limited

​429 trial_compute_limit_reached

​503 no_ready_machine

​402 credit_required

​Still stuck

Why did my sandbox stop?

A sandbox does not answer

”This sandbox is responding normally, so there is nothing to recover.”

”Recovery already started. Give it N more minute(s) before trying again.”

”This sandbox runs on a machine that cannot be power-cycled.”

A sandbox is in error

A command was killed: exit code 137 (out of memory)

Out-of-disk emails

A stop does not finish

Error messages

`409 snapshot_data_expired`

`409 sandbox_starting`

`409 sandbox_not_ready`

`409 machine_not_running`

`409 sandbox_stopping`

`429 rate_limited`

`429 trial_compute_limit_reached`

`503 no_ready_machine`

`402 credit_required`

Still stuck