Exit codes
The small, stable set of exit codes every coma command uses, and which error codes map to each.
Every coma command exits with one of the codes below. Each error has a stable error code, and each error code maps to exactly one exit code. Scripts can branch on the exit code and read error.code from the --json error envelope for detail.
| Exit | Meaning | Error codes |
|---|---|---|
| 0 | Success | |
| 1 | Internal or uncategorised failure | internal, and any code not listed elsewhere |
| 2 | Invalid usage | invalid_argument, confirmation_required, machine_target_required, engine_selection_required, workspace_manifest_ambiguous, workspace_manifest_invalid, workspace_target_required |
| 3 | Not found | not_found, context_not_found, machine_not_found, engine_not_found, endpoint_not_found, docker_context_not_found, workspace_manifest_not_found, workspace_not_found |
| 4 | Conflict or already exists | already_exists, conflict, context_already_exists, machine_already_exists, machine_in_use, endpoint_socket_conflict, docker_context_conflict, docker_context_drifted, local_port_in_use, workspace_plan_blocked, workspace_delete_blocked |
| 5 | Authentication or permission | permission_denied, unauthenticated, machine_auth_failed, ssh_host_key_unknown, ssh_host_key_mismatch, ssh_key_unavailable, bootstrap_privilege_required, engine_permission_denied |
| 6 | Unavailable: network, machine or dependency | network_unavailable, machine_unreachable, machine_discovery_failed, ssh_proxy_failed, bootstrap_failed, engine_unavailable, endpoint_backend_unavailable, daemon_unavailable |
| 7 | Timeout | timeout, lock_timeout |
| 8 | Unsupported or not implemented | unsupported, not_implemented, machine_unsupported_os, bootstrap_plan_failed, sync_mode_unsupported, workspace_api_version_unsupported, workspace_target_kind_unsupported |
| 10 | Local state, config or a failed check | invalid_config, state_corrupt, migration_failed, state_schema_too_new, doctor_failed |
| 130 | Interrupted (Ctrl-C or SIGTERM; 128 + SIGINT) | interrupted |
Usage errors
An unknown command (such as coma machin), an unknown flag, a missing or extra argument, or an invalid value in a flag or in COMA_LOG_LEVEL, COMA_LOG_FORMAT or COMA_SYNC_ALLOW_BIDIRECTIONAL exits with 2 (invalid_argument). The error says what was wrong; for a mistyped command it can suggest a close match (also in error.details.suggestions with --json).
Doctor commands
coma doctor, coma endpoint doctor and coma docker-context verify exit with 10 when any check reports FAIL. Warnings alone exit with 0. coma docker-context verify exits with 4 (docker_context_drifted) when the context was changed outside COMA.
Interrupts
Ctrl-C or SIGTERM exits with 130. When coma docker or coma podman is interrupted, COMA forwards the interrupt to the machine. If the remote command ignores it, COMA says it may still be running and exits with 130.
Passthrough
coma docker and coma podman run the engine's CLI on the machine and exit with that command's own exit status. An exit of 7 from coma docker run … sh -c 'exit 7' is the container's, not a COMA timeout. Errors COMA raises itself, such as an unreachable machine, use the table above.