More
Troubleshooting
PyBox fails closed: when something isn't right, it refuses and tells you why. Here's what each message means.
Setup and the VM#
| You see | What to do |
|---|---|
restricted runtime is not set up (run: pybox setup) | Run pybox setup, read the plan, then pybox setup --yes. |
dedicated VM is not running (start it with: pybox vm start …) | Run pybox vm start. Nothing else starts the VM for you. |
required tool missing | Install the prerequisites: brew install colima docker. |
tool is not a private executable | The docker or colima binary is writable by other users. Fix its permissions or reinstall it with Homebrew. |
supports macOS on Apple Silicon (arm64) only | PyBox doesn't run on Intel Macs, Linux or Windows yet. |
conflict … existing file differs; will not overwrite during setup | A file in ~/.pybox/runtime isn't what PyBox expects. Look at it, then move it aside yourself and run setup again. |
started, but verification failed … stopping | vm start found a setting it doesn't accept (shared folders, port forwarding, a missing image) and stopped the VM. Run pybox doctor for details. |
Running programs#
| You see | What to do |
|---|---|
another PyBox run or cleanup holds lifecycle admission | One run at a time, by design. Try again when the other finishes. |
reconciliation blocks execution: … an owned target is still running | A previous program is still running. Its timer stops it within about 3 seconds; try again. |
reconciliation blocks execution: … unresolved create | An earlier run was interrupted while its box was being created. After it expires (about 3 minutes), run pybox cleanup --resolve-attempt <run>. Why. |
trusted collector did not arm before START | The kernel watcher didn't start in time, so PyBox refused to run the program unobserved. Try again; if it repeats, restart the VM. |
| Exit code 137 | By itself it only means "killed". Read observed.termination and explanations in the receipt for the evidence. |
stdout_truncated: true, or "(cut)" on the receipt | The program printed more than the output cap. Raise --max-output-bytes (up to 65,536), or write the result to a file with --output. |
image 'data' is not installed | Build it once: pybox setup --yes --with data. For your own images: pybox image build NAME --lock FILE. |
lock line N is not an exact pin with --hash=sha256:… | Every package needs an exact version and a hash. Generate the file with uv pip compile … --generate-hashes (see your own packages). |
another image build or removal is running | One at a time, so the image record is never written from a stale copy. Wait for the other one. |
could not write outputs (nothing was written) | The output folder changed during the run, or a name clashed. Nothing was half-written; run again with a new --output folder. |
image 'data' was built from a different recipe | PyBox was upgraded with a new package list. Rebuild: pybox setup --yes --with data. |
output folder is not empty | --output must be a new or empty folder, so nothing is ever overwritten. Pick a new name. |
unsupported file name | Input and output names may use letters, digits, ., _ and -, up to 4 folders deep, with no hidden files. Rename the file. |
| "no transfer received" on the receipt | The program didn't finish normally (it hit the deadline, or exited with os._exit), so its output files never came back. |
MCP#
| You see | What to do |
|---|---|
One run is already active; no request was queued | Wait for the current call. PyBox runs one at a time. |
Session tool-call limit reached | 32 calls per session. Restart the server. |
A call returns isError with cleanup NOT_ATTEMPTED | The VM isn't running. Start it with pybox vm start. |
… (set by the server) | The agent asked for a longer time limit or an image the server doesn't allow. Raise --max-timeout or add the image to --images in the MCP config. |
Still stuck?#
Run pybox doctor and open an issue on GitHub with its output.