Error codes

A code is a promise: it names a kind of failure that keeps meaning the same thing across releases. Branch on the code, never on the sentence.

Validation codes

Adding one is a deliberate act. A test refuses any code the loader emits that is not enumerated, and any enumerated code that nothing emits, so this table cannot drift in either direction.

Emitted while loading and checking the project file. Each failure carries the code, the path that produced it, and where possible the line and the resolving command.

Code	Means
`app_required`	metadata.name is required
`backup_credentials_invalid`	decrypted backup credentials are missing or malformed
`backup_driver_unsupported`	a runnable service driver has no qualified executable backup contract
`backup_encryption_unverified`	the selected target cannot prove the encryption mode required by the recovery kind
`backup_image_revert_unsafe`	tag rendering would strand an effective backup prerequisite
`backup_interruption_not_authorized`	the selected recovery contract needs a recurring stopped-service window the author did not permit
`backup_retention_unsupported`	the declared recovery history cannot map to supported retention semantics
`backup_service_image_unpublished`	the protected service image lacks verified publication provenance
`backup_state_incomplete`	a protected service does not record what it is protected by
`backup_target_not_independent`	a backup target shares the protected failure domain
`backup_target_unknown`	a backup policy selects no declared backup target
`compose_container_name`	a referenced service fixes its container name, which Onebox owns
`compose_extends`	a referenced service uses extends, which hides what runs
`compose_file_unparsable`	a referenced Compose file is not valid YAML
`compose_file_unreadable`	a referenced Compose file could not be read
`compose_ingress_attached`	a referenced service already attaches the ingress network
`compose_network_mode`	a referenced service sets network_mode, which conflicts with the network it needs
`compose_onebox_label`	a referenced service carries a label in a namespace Onebox generates into
`compose_ref_malformed`	a Compose reference is not of the form path#service
`compose_service_missing`	a referenced Compose file has no such service
`compose_traefik_label`	a referenced service carries routing labels while also declaring a route
`connection_variable_claimed`	an authored value claims a name a managed-service connection supplies
`derived_name_too_long`	a name Onebox derives exceeds the runtime’s limit
`drill_schedule_too_sparse`	the declared drill cadence is too sparse to keep restore proof within its maximum age
`eject_destination_exists`	the ejection destination already exists
`eject_failed`	the runtime could not be handed over
`eject_nothing_to_do`	every workload already references a Compose file
`env_file_missing`	an environment file the project declares is not on disk
`env_file_unreadable`	an environment file the project declares cannot be read
`health_port_unknown`	an http health check has no port to probe and none can be derived
`host_prerequisite_unmet`	host software a deploy needs is missing or unusable
`identifier_collision`	a name is used by both a workload and a service
`image_unresolved`	a build-sourced workload has no resolved image for this release
`internal_copy_failed`	a project could not be copied internally
`internal_decode_failed`	a normalised project could not be decoded
`no_environment`	a project must declare at least one environment
`no_workload`	a project must declare at least one workload
`override_invalid`	an override produced a value the contract does not accept
`override_not_permitted`	a field that may not vary per environment
`override_unknown_service`	an override names a service the project does not declare
`override_unknown_workload`	an override names a workload the project does not declare
`path_absolute`	a repository path may not be absolute
`path_escapes_repository`	a path resolves outside the project directory
`path_parent_reference`	a bind source contains a parent-directory segment
`path_unresolvable`	a path could not be resolved
`preflight_env_incomplete`	an environment file is missing keys the project requires
`prerequisite_has_no_health`	a wait for health names something with no health check
`project_invalid`	a value that does not satisfy the contract
`project_unparsable`	the project file is not valid YAML, or is not a mapping
`project_unreadable`	the project file could not be read
`recovery_objective_unsupported`	the service driver, target, or version cannot execute the declared recovery kind
`render_failed`	the runtime could not be rendered
`route_collision`	two workloads claim the same address
`route_without_proxy`	a route is declared with nothing to route it
`schedule_untranslatable`	a cron expression whose meaning the host’s scheduler cannot preserve
`schema_identity_missing`	the Application declares no apiVersion
`schema_identity_unsupported`	the Application declares an apiVersion this binary does not speak
`schema_kind_unsupported`	the authored resource is not an Application
`server_unreachable`	the server could not be reached
`service_image_digest_unavailable`	the immutable service image is unavailable from registry and exact cache
`service_image_patch_disable_pending`	protected image refresh is refused while disablement is pending
`service_patch_unsupported`	no exact qualified protected current-to-candidate image transition exists
`service_settings_unsupported`	a setting was declared for a driver with no way to apply it
`stateful_replicas`	a workload keeping durable state asks for more than one replica
`strategy_ungated`	a rolling release is asked for by a workload with no health check to gate it
`unknown_environment`	an environment the project does not declare
`unknown_field`	a field the contract does not define
`unknown_prerequisite`	a prerequisite names something the project does not declare
`unknown_service_driver`	a service names a driver Onebox has no implementation for
`workload_malformed`	a workload is not a mapping
`workload_source`	a workload declares other than exactly one of build, image or compose

Operation codes

Raised while a command runs, rather than while the project file is read. These are the codes a deploy, a rollback, a secret rotation or an audited exec puts in the error.code field, so they are the set to branch on when automating.

A blank command is deliberate: some failures have no honest Onebox command that resolves them. A local artifact that could not be written is fixed on the filesystem, not by running the tool again. An angle-bracketed command names a step to complete rather than a line to run verbatim.

Code	Means	Guidance role	Command
`activation_refused`	the release cannot be activated from its recorded manifest state	resolving	`ob abort --output ndjson`
`approval_expired`	the local confirmation is older than its validity window	next	`ob approve --plan <path>`
`approval_failed`	the approval artifact is missing, unreadable, or not bound to this plan	next	`ob approve --plan <path>`
`artifact_write_failed`	a requested local artifact could not be written	—	—
`cancelled`	the operation was cancelled or interrupted; consult the journal for how far it got	diagnostic	`ob audit --output json`
`command_failed`	the command failed; diagnostic detail is on stderr	—	—
`compose_invalid`	the Compose project could not be loaded	diagnostic	`ob validate --output json`
`compose_not_found`	no Compose file was found to adopt	resolving	`ob init --output json`
`config_exists`	a project file already exists and init refuses to overwrite it	diagnostic	`ob validate --output json`
`config_write_failed`	the project file could not be written	—	—
`confirmation_failed`	the backup report for this local confirmation could not be loaded or does not bind to the plan	next	`ob approve --plan <path> --backup-report <path>`
`divergence_detected`	the live application state has diverged from its intended state	diagnostic	`ob audit --output json`
`doctor_failed`	a local readiness check failed	—	—
`exec_failed`	the audited exec could not be completed	diagnostic	`ob status --output json`
`execution_count_invalid`	execution count must be between 1 and 1000	—	—
`execution_inspect_failed`	durable execution could not be read	—	—
`execution_list_failed`	durable executions could not be listed	—	—
`finalize_refused`	the release cannot be finalized because the recorded activation evidence disagrees with the live host	diagnostic	`ob status --output json`
`host_environment_mismatch`	this host is claimed by a different environment of the same application, which would share its container and volume names	diagnostic	`ob preflight --output json`
`host_owner_mismatch`	this host is owned by a different Onebox application, and one host has one owner	diagnostic	`ob preflight --output json`
`interrupted`	the operation’s client went away before its outcome could be recorded	diagnostic	`ob audit --output json`
`job_history_failed`	the job’s retained execution records could not be read	diagnostic	`ob status --output json`
`job_input_invalid`	an —input flag is not NAME=VALUE, or names the same input twice	diagnostic	`ob canonical --output json`
`job_logs_failed`	the host-supervised job journal could not be read	next	`ob job history <job> --output json`
`job_plan_failed`	the one-shot job plan could not be produced	next	`ob job plan <job> --output json`
`logs_failed`	log retrieval failed	diagnostic	`ob status --output json`
`manifest_invalid`	a release manifest is not valid closed JSON for its schema	diagnostic	`ob status --output json`
`manifest_missing`	a release directory carries no manifest, so its lifecycle state is unknown	diagnostic	`ob status --output json`
`manifest_mode_unsafe`	a release manifest is not mode 0600 on the host	diagnostic	`ob doctor --output json`
`manifest_read_failed`	a release manifest could not be read from the host	diagnostic	`ob status --output json`
`manifest_schema_unknown`	a release manifest declares a schema this binary does not support	diagnostic	`ob version --output json`
`manifest_write_failed`	a release manifest could not be written to the host	diagnostic	`ob status --output json`
`migration_backup_required`	a migration-effect step requires a plan-bound backup report or an audited override	next	`ob plan --backup-report-out <path>`
`migration_gate_closed`	the interrupted release ran rollback-unknown data effects, so the requested recovery action is refused	resolving	`ob resume --output ndjson`
`operation_failed`	the operation failed; inspect stderr and journal evidence	diagnostic	`ob audit --output json`
`output_mode_incompatible`	the requested output mode is incompatible with this command	diagnostic	`ob help`
`plan_expired`	the sealed plan is older than its validity window	next	`ob plan --output json`
`plan_failed`	the plan could not be produced; inspect stderr for local diagnostics	diagnostic	`ob validate --output json`
`plan_required`	this command requires a sealed plan when run with structured output	next	`ob plan --output json`
`post_activation_failed`	the release is serving, but the work after activation did not finish	resolving	`ob resume --output ndjson`
`preflight_failed`	a target readiness check failed before any mutation	—	—
`recovery_incomplete`	recovery did not reach its verified terminal state	resolving	`ob resume --output ndjson`
`rollback_target_missing`	no previously serving release is recorded as a rollback target	next	`ob plan --output json`
`schedule_list_failed`	the scheduled jobs’ timer state could not be read	diagnostic	`ob status --output json`
`secret_cleanup_pending`	the rotation is applied and verified, but removing the retired generation did not finish	resolving	`ob secrets push --output ndjson`
`secret_declaration_not_deployed`	the deployed release does not declare this secret graph	next	`ob plan --output json`
`secret_entry_not_selected`	more than one editable secret source exists, so an entry identifier is required	diagnostic	`ob secrets list --output json`
`secret_generation_not_deployed`	the deployed release predates opaque secret generations	next	`ob plan --output json`
`secret_recovery_incomplete`	secret recovery did not reach its verified terminal state	resolving	`ob secrets push --output ndjson`
`secret_rotation_rolled_back`	an interrupted rotation was restored to its prior generation and the requested payload was not applied	resolving	`ob secrets push --output ndjson`
`sops_failed`	the SOPS editor exited with a failure	—	—
`sops_source_missing`	a declared encrypted source file does not exist	diagnostic	`ob validate --output json`
`status_failed`	the status snapshot could not be read	diagnostic	`ob doctor --output json`
`unknown_runtime_target`	the requested runtime target is not declared	diagnostic	`ob status --output json`

Lifecycle failure codes

Every code here is raised by a path in the shipped binary, checked against the source by a test in both directions. The table is computed, not maintained by hand.

The failure contract shared by plans, event streams, terminal results, status and doctor. Each carries a stable code and one safe command in its semantic role; diagnostic detail stays in restricted local evidence, never in the public record.

Code	Means	Guidance role	Command
`backup_conflict`	another protected-service operation holds the serialization boundary	diagnostic	`ob status --output json`
`backup_disable_pending`	backup removal is waiting for an authorized safe prerequisite reversal	diagnostic	`ob status --output json`
`backup_disablement_overdue`	backup disablement remains pending beyond its action deadline	diagnostic	`ob status --output json`
`backup_driver_unsupported`	the service driver has no qualified executable backup contract	diagnostic	`ob validate --output json`
`backup_encryption_unverified`	the selected backup destination cannot prove its required encryption mode	diagnostic	`ob validate --output json`
`backup_image_revert_unsafe`	the requested image reversion would strand an effective backup prerequisite	diagnostic	`ob status --output json`
`backup_interruption_not_authorized`	the recovery contract requires a recurring stopped-service window the author did not permit	diagnostic	`ob validate --output json`
`backup_retention_unsupported`	the declared recovery history cannot map to qualified native retention semantics	diagnostic	`ob validate --output json`
`backup_service_image_unpublished`	no qualified immutable backup image is published for the observed service base	diagnostic	`ob status --output json`
`backup_target_not_independent`	the backup target shares the protected failure domain	diagnostic	`ob validate --output json`
`backup_target_unknown`	the backup policy selects no declared backup target	diagnostic	`ob validate --output json`
`drill_schedule_too_sparse`	the declared drill cadence is too sparse to keep restore proof within its maximum age	diagnostic	`ob validate --output json`
`recovery_objective_unsupported`	the selected driver, version, or target cannot execute the declared recovery kind	diagnostic	`ob validate --output json`
`service_image_digest_unavailable`	the exact immutable service image required by recovery is unavailable	diagnostic	`ob status --output json`
`service_image_patch_disable_pending`	service image refresh is refused while safe backup disablement is pending	diagnostic	`ob status --output json`
`service_patch_unsupported`	no exact qualified protected current-to-candidate transition exists	diagnostic	`ob status --output json`