---
title: Exit codes
description: Every process exit status the CLI uses, the stable code that accompanies it, what it means, and the platform finding behind it.
---

## 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](/microvms-agentd/reference/envelope/) has the full shape.

5 of the rows name a finding. A finding is a section of the platform notes, [measured platform behavior](/microvms-agentd/internals/platform/), 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](/microvms-agentd/internals/platform/#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](/microvms-agentd/internals/platform/#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](/microvms-agentd/internals/platform/#runhookpayload-arrives-wrapped-not-as-the-body) |
| `8` | `ERR_WINDOW_CLOSED` | the launch-time suspended window passed, so there is nothing to resume | [`idlePolicy`](/microvms-agentd/internals/platform/#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](/microvms-agentd/internals/platform/#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.