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

• CLICKHOUSE_MSSQL_TARGET_MAX_CURSOR_UNSAFE, MYSQL_MSSQL_TARGET_MAX_CURSOR_UNSAFE, MSSQL_MSSQL_TARGET_MAX_CURSOR_UNSAFE, and POSTGRES_MSSQL_COLUMN_CURSOR_UNSAFE reject lossy target-derived single-column cursors before source or target I/O and point to complete route alternatives.
• POSTGRES_XMIN_INITIAL_CONTRACT_INVALID and POSTGRES_XMIN_INCREMENTAL_CONTRACT_INVALID reject an incomplete initial/incremental handoff pair before connector I/O.
• POSTGRES_XMIN_EXECUTION_INVALID and POSTGRES_XMIN_HANDOFF_ROUTE_UNSUPPORTED reject malformed phase authoring or a non-PostgreSQL→MSSQL route.
• 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_MSSQL_ASSET_URI_INVALID: MSSQL Airflow Asset outlets must be mssql://{host}:{port}/{database}/{schema}/{table} with deployment-owned asset_authority (AIP-60; never connection_ref as host).
• DPONE_MSSQL_TARGET_DATABASE_AUTHORITY_REQUIRED, DPONE_MSSQL_STAGING_DATABASE_AUTHORITY_REQUIRED, and DPONE_MSSQL_STATE_DATABASE_AUTHORITY_REQUIRED: every target, staging, and state database touched by a target-atomic MSSQL route needs an immutable registry pin.
• DPONE_MSSQL_DATABASE_AUTHORITY_INVALID: a database pin is open, malformed, or non-canonical.
• DPONE_POSTGRES_SOURCE_AUTHORITY_REQUIRED: a governed PostgreSQL→MSSQL route has no deployment-signed source pin.
• DPONE_POSTGRES_SOURCE_AUTHORITY_INVALID: the signed source document is incomplete, open, or ambiguous.
• DPONE_POSTGRES_SOURCE_DATABASE_AUTHORITY_MISMATCH: route/connection database coordinates do not select the signed database.
• DPONE_SCAFFOLD_APPLY_FAILED: scaffold I/O failed and the returned rollback receipt may require manual reconciliation.
• DPONE_DOMAIN_CATALOG_MEMBERSHIP_CONFLICT: the domain catalog membership entry for a scaffolded pipeline could not be written safely and must be reconciled manually.

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