Exit codes
The five exit codes every engine-dmo and engine-cms command uses (0 success, 1 error, 2 pending or unconfirmed, 3 invalid configuration, 4 degraded), and which commands return 2 and 4 and why.
Every command exits with one of five codes, so a script or CI step can act on the result without parsing output. Under --json the code is also in the output (the envelope’s exit).
| Code | Name | Meaning |
|---|---|---|
0 | Success | The command did what it was asked, or there was nothing to do |
1 | Error | It failed: a database it could not reach, a file it could not write, a refusal that is not about confirmation |
2 | Pending | Changes are pending, or the command refused for want of confirmation |
3 | Invalid | The configuration is invalid, or a flag’s value cannot be used |
4 | Degraded | It ran, and something it depends on is not answering |
engine-dmo migrate status
case $? in
0) echo "up to date" ;;
2) engine-dmo migrate up ;;
*) exit 1 ;;
esac Exit 2: pending or unconfirmed
| Command | Exits 2 when |
|---|---|
migrate status | Any migration is pending |
schema plan | The configuration differs from the database |
schema apply | The plan is destructive and not approved; an id in the files replaces a stored one not named by --replace; the plan holds a change this engine cannot apply yet; or a destructive plan was not confirmed on the terminal |
serve | Migrations are pending (and migrate.on_boot is refuse), or the configuration has drifted (and schema.on_drift is refuse) |
dev authoring verbs with --apply | The resulting plan is destructive: review it and run schema apply |
search rebuild | A rebuild, purge or check is already running, or held by another worker |
search verify | The index has drifted from what is published |
ai test, crm dedupe | The AI budget is spent |
seed reset, user reset-mfa, mail suppression remove, content purge, site retire, crm erase, newsletter send, broadcast send and similar | The confirming flag (--confirm or --yes) is missing |
Exit 3: invalid
check, config validate, serve and every command that loads the project exit 3 when the configuration or a template is invalid, after printing every problem with its file, line and column. Several commands also exit 3 for a flag value they cannot use (an address that is not loopback for docs serve, an AI command with no provider configured, a sar address or --out it cannot use). audit verify exits 3 when nothing is chained, and 1 on a break in the chain.
Unknown commands and flags exit 1
help --json describes exit 3 as “configuration invalid, or a bad invocation”, but an unknown command, an unknown flag or a missing required flag exits 1 in this release. Treat any non-zero code other than 2 and 4 as a failure.
Exit 4: degraded
| Command | Exits 4 when |
|---|---|
health | The server did not answer 200 (within --wait, when given) |
jobs list, jobs retry | The database does not answer |
search status, search test, search verify | The search backend does not answer |
ai status, ai test | The AI provider does not answer; the AI features are unavailable and nothing else is affected |
analytics report --format pdf | The PDF could not be rendered |
crm dedupe | The AI provider behind duplicate detection is not answering (exit 2 when the AI budget is spent) |
Related
- CLI: every command.
- Error codes: the
MRD-nnnncode a refusal carries.
Environment variables
Which environment variables the engine reads directly (very few), the conventional names a project's engine.yaml interpolates, the variables commands read secrets from, and the variables the engine sets for child processes.
Error codes
Every stable MRD error code the engine reports, with its cause and its fix.