Exit codes

1. How to read the table

Every invocation ends with one of the 17 statuses below. The process exit status is the coarse signal for a shell; the code string is the stable one for a program, and it arrives in the error envelope’s code field beside an exitCode that matches the process status. The envelope has the full shape.

5 of the rows name a finding. A finding is a section of the platform notes, measured platform behavior, that documents the condition the code reports; the link opens that section.

2. The codes

Exit	Code	Meaning	Finding
0	none	the command did what it said	none
1	ERR_UNEXPECTED	an exception no handler claimed — a bug in this CLI, not the platform	none
2	ERR_INVALID_ARG	the request was refused locally, before any AWS call	none
3	ERR_RETRYABLE	a transient condition; run the identical command again	Endpoint authentication
4	ERR_CREDENTIALS	an identity is wrong or absent; waiting will not fix it	none
5	ERR_PROTOCOL	the daemon rejected the request on its merits	none
6	ERR_BUILD_WEDGED	the image build was never scheduled — the clientToken replay signature	clientToken is a permanent idempotency key
7	ERR_LAUNCH_DIED	the MicroVM reached a terminal state before RUNNING; read stateReason	runHookPayload arrives wrapped, not as the body
8	ERR_WINDOW_CLOSED	the launch-time suspended window passed, so there is nothing to resume	idlePolicy
9	ERR_PLATFORM	a control-plane failure with no more specific class	none
10	ERR_TIMEOUT	a client-side deadline elapsed; the VM and the exec are untouched	none
11	ERR_INTERRUPTED	interrupted after launch; teardown ran and any leak is named in the payload	The build log group survives Terraform
12	ERR_PRECONDITION	a prerequisite is missing — run microvm doctor	none
13	ERR_EXEC_FAILED	the sandbox worked and the command in it exited non-zero	none
14	ERR_NAME_TAKEN	the VM name is registered to a live VM; refused locally, before any AWS call	none
15	ERR_CONFIG	the project config file is missing, malformed, or out of domain; refused locally — fix the file, or pass --no-config	none
16	ERR_SYNC	run <DIR> could not pack the directory or write an artifact back; the failure is on this machine’s filesystem, not the platform’s	none

3. Provenance

This page is generated from docs/manifest.json, the output of microvm manifest. This page reads data.exitCodes; the finding strings are section titles the CLI carries beside each code. site/scripts/gen-reference.mjs writes it into the site’s content directory on every pnpm run sync, so an edit made here is overwritten by the next run.

To change the page, change the source. Regenerate the source with mise run manifest from the repository root; mise run manifest:check fails when the committed file no longer matches what the binary emits.