Errors and exit codes
Stable process exits, error envelopes, and MM error codes.
Exit categories
| Exit | Meaning |
|---|---|
0 | Success, valid status, or no difference. |
1 | Local I/O, state, terminal, stale-plan, or difference result, depending on the command. |
2 | Invalid request, configuration, environment, target, or build input. |
3 | Security, secret-provider, runtime, process, or capability failure. |
130 | Interrupted by Ctrl-C or termination signal. |
The category is stable; command-specific successful diagnostics can deliberately return a non-zero status as described below.
Error output
Human output uses error[MM_CODE]: message. With --output json, command
errors are written to stderr as a JSON error envelope and remain JSON:
{ "error": { "code": "MM_CONFIG_NOT_FOUND", "message": "..." } }
CLI parsing failures, including unknown options, missing values, and invalid
enum values, use MM_CLI_PARSE. They honor --output json even though parsing
did not produce a command. A failure while rendering an error is reported as
MM_OUTPUT on stderr.
Recoverable setup errors also include error.recovery: a typed issue, a
plain-language help message, and a command argument array. Suggested commands
preserve explicit root, mm-home, environment, target, and runtime selections.
Human output prints the corresponding quoted command. Other errors may have
recovery: null.
Stable command error codes
| Code | Exit | Category |
|---|---|---|
MM_CONFIG_NOT_FOUND | 2 | No .config/mm.yaml found from the selected root or its parents. |
MM_CONFIG_READ | 2 | Configuration could not be read. |
MM_CONFIG_PARSE | 2 | YAML, UTF-8, location, or typed-schema parse failure. |
MM_CONFIG_INVALID | 2 | Validation returned one or more errors. |
MM_CONFIG_EXISTS | 2 | Initialization would replace an existing configuration. |
MM_ENVIRONMENT_REQUIRED | 2 | No CLI, environment-variable, or default environment selection. |
MM_ENVIRONMENT | 2 | Environment compilation or operation error. |
MM_TARGET | 2 | Target selection or definition error. |
MM_BUILD | 2 | Build planning or input error. |
MM_SECRET | 3 | Secret provider or lifecycle error. |
MM_SECRET_INCOMPATIBLE | 3 | Storage, delivery, runtime, workload, or rollback combination is unsupported. |
MM_TARGET_OPERATION_IN_PROGRESS | 3 | Another mutation holds the target operation lock. |
MM_SECURITY | 3 | A path, ownership, approval, or other security policy rejected the operation. |
MM_PROCESS_SPAWN | 3 | A required subprocess could not start. |
MM_PROCESS_TIMEOUT | 3 | A subprocess exceeded its bounded timeout. |
MM_PROCESS_FAILED | 3 | A subprocess exited unsuccessfully. |
MM_RUNTIME_RESPONSE | 3 | Runtime output could not be interpreted safely. |
MM_RUNTIME_UNSUPPORTED | 3 | The selected runtime lacks a required advertised capability. |
MM_IO | 1 | Other local filesystem or stream I/O failure. |
MM_STATE | 1 | Private state-store failure. |
MM_SWARM_PLACEMENT | 2 | A service's placement or shared-volumes cannot be satisfied on the cluster. |
MM_TERMINAL | 1 | Prompt or terminal contract failure. |
MM_CLI_PARSE | Clap status, normally 2 | Arguments could not be parsed. |
MM_OUTPUT | original status | Fallback when mm cannot print the intended output. |
mm also exits with MM_SECURITY when an AI agent runs it directly instead of
through the MCP server. See
mm refuses to run for an agent.
Validation and status payloads also contain specific MM_* diagnostic codes.
Those codes identify individual findings; process status is determined from
their severity and category rather than from the presence of warnings.
Readiness findings include MM_STATE_LEGACY, MM_TARGET_MISSING,
MM_RUNTIME_REQUIRED, MM_BUILD_REQUIRED, and MM_SERVICES_REQUIRED.
Doctor reports these findings together on stdout, including in JSON mode, and
marks dependent checks as blocked until they can be evaluated.
Diagnostic commands
mm config validate returns 2 when validation has an error, otherwise 0.
mm doctor returns 2 when its aggregate configuration, CA, local-route TLS,
or shared-service report contains an error. If that report is valid, it returns
3 when the runtime is unavailable or has an error diagnostic, otherwise 0.
An explicit --check-updates returns 1 when the stable manifest is unreachable
or invalid and includes an actionable unavailable report. Up-to-date,
update-available, installed-newer, and unsupported-platform states do not by
themselves fail unrelated doctor checks.
mm doctor recover-state prints a read-only recovery review. Applying it requires
the exact --plan HASH --yes; successful recovery reports the backup path.
See legacy-state recovery
for what is reset and preserved.
mm service status returns 2 for configuration diagnostics, 3 for runtime or
provider diagnostics, and 0 otherwise. Warnings alone do not make either
command fail.
Environment status/check/setup operations return 3 for error diagnostics
MM_SECRET_PROVIDER_UNAVAILABLE, MM_SECRET_ACCESS_DENIED, or
MM_SECRET_INVALID; other error diagnostics return 2; warnings return 0.
mm env diff first applies those environment diagnostic rules. When status is
valid, it always prints the diff and returns 1 if the materialized file would
change or 0 if it is unchanged. Exit 1 is therefore a difference result,
not an execution error.