Domain-first self-service error overview

Audience: pipeline authors, domain owners, CI maintainers, and platform engineers.

Domain-first commands return stable dpone.error.v1 codes. Start with the first error in JSON output; later errors may be consequences of the same authoring problem.

Exit	Meaning	First action
1	Authoring, discovery, or validation failed	Open the code-specific page and repair editable sources.
2	Request or project configuration is invalid	Check command help and dpone.yaml.
4	Confinement, locking, or CAS safety failed	Stop concurrent writes and inspect the rejected path or authority.
5	Unexpected internal failure	Preserve redacted output, version, and trace id for maintainers.

Common authoring errors

• DPONE_PROJECT_LAYOUT_MIGRATION_REQUIRED: flat, domain-first, or mixed authority cannot be adopted implicitly.
• DPONE_DOMAIN_OWNERSHIP_MISSING: initialize the owning domain before its pipeline.
• DPONE_PIPELINE_DOMAIN_MISMATCH: directory/source ownership or an external recipe domain conflicts.
• DPONE_PIPELINE_ID_DUPLICATE: pipeline ids are unique across the project.
• DPONE_RECIPE_ROUTE_CONFLICT: choose either an exact recipe or a capability route for scaffolding.
• DPONE_AIRFLOW_DISABLED: the pipeline is valid but intentionally excluded from Airflow.
• DPONE_SCAFFOLD_APPLY_FAILED: scaffold I/O failed and the returned rollback receipt may require manual reconciliation.

Discovery and CI errors

• DPONE_DISCOVERY_PATH_INVALID and DPONE_LAYOUT_ROOT_INVALID identify unsafe paths, unexpected depth, or symlink escape.
• DPONE_WORKLOAD_INDEX_INVALID means a baseline is unsafe, stale, forged, or outside the closed schema.
• DPONE_WORKLOAD_INDEX_APPROVAL_MISMATCH means candidate bytes changed after protected approval.
• DPONE_WORKLOAD_INDEX_PROMOTION_CONFLICT means the accepted baseline changed before compare-and-swap.
• DPONE_WORKLOAD_INDEX_PROMOTION_RECOVERY_REQUIRED means durable replacement cleanup requires operator reconciliation.
• DPONE_WORKLOAD_INDEX_PROMOTION_REQUEST_INVALID means bootstrap/change guards were combined incorrectly.
• DPONE_DISCOVERY_LIMIT_EXCEEDED means the bounded local discovery budget was exceeded.
• DPONE_SELECTION_STATE_CHANGED means selected authority changed before the operation could commit.
• DPONE_AUTHORING_SOURCE_CHANGED_DURING_BUILD means the checked source changed before preview promotion.

All fixes change editable authoring sources or CI inputs only. Do not edit generated release/deployment artifacts, fingerprints, credentials, or Vault configuration to make an error disappear.

Return to the domain-first tutorial