What causes ContractBreakingChangeError?

A column was removed from the model's SQL output but still declared in the model contract with required: true. A column's data type was changed in the SQL (e.g., from INTEGER to VARCHAR) without bumping the model version. A developer renamed a column in the model output without updating the contract YAML and without creating a new model version

How do I fix ContractBreakingChangeError?

Step 1: Run dbt compile or dbt parse to see the full breaking change error message, which names the specific column and the nature of the incompatibility.. Step 2: If the change is intentional, create a new model version (e.g., v2) with the updated schema, and set it as latest_version. Keep the old version available for existing consumers during the transition.. Step 3: If the change was accidental, revert the model SQL to match the contracted column list and data types.. Step 4: Update all downstream models that depend on the old version to reference the new version once they have been migrated.

Critical severitydata_quality

Power BI Refresh Error:
ContractBreakingChangeError

What does this error mean?

dbt detected a breaking change to a versioned model's enforced contract — such as a column removal or data type change — and rejected the run to prevent downstream consumers from silently receiving incompatible data.

Common causes

1A column was removed from the model's SQL output but still declared in the model contract with required: true
2A column's data type was changed in the SQL (e.g., from INTEGER to VARCHAR) without bumping the model version
3A developer renamed a column in the model output without updating the contract YAML and without creating a new model version

How to fix it

1Step 1: Run dbt compile or dbt parse to see the full breaking change error message, which names the specific column and the nature of the incompatibility.
2Step 2: If the change is intentional, create a new model version (e.g., v2) with the updated schema, and set it as latest_version. Keep the old version available for existing consumers during the transition.
3Step 3: If the change was accidental, revert the model SQL to match the contracted column list and data types.
4Step 4: Update all downstream models that depend on the old version to reference the new version once they have been migrated.

Frequently asked questions

Does dbt contract enforcement only apply to versioned models?

No. Model contracts can be applied to any model via contract: enforced: true in the model's YAML. However, breaking change detection with version management is most powerful when used with versioned models.

What columns count as breaking changes?

Removing a column, changing a column's data_type, or changing a column's constraints (e.g., removing not_null) are all treated as breaking changes under dbt's contract enforcement.