What causes ContractBreakingChangeError?

A developer removed a column from a model that has contract: enforced in its YAML definition. The data type of a contracted column was changed (e.g., INT to VARCHAR) without updating the contract. A NOT NULL or PRIMARY KEY constraint was removed from a contracted column. The model's schema.yml was not updated to reflect legitimate schema changes before running dbt

How do I fix ContractBreakingChangeError?

Step 1: Read the error message to identify which column or constraint was removed or changed.. Step 2: If the change is intentional: update the contract definition in the model's schema.yml to reflect the new schema, treating it as a versioned breaking change.. Step 3: If the change was accidental: restore the column or constraint in the model SQL.. Step 4: Consider using dbt model versioning (v:) to introduce a new version of the model and deprecate the old one, giving consumers time to migrate.. Step 5: Run dbt parse and dbt compile to validate the updated contract before re-running.

Critical severitydata_quality

Power BI Refresh Error:
ContractBreakingChangeError

What does this error mean?

dbt rejected a model change because it violates an enforced data contract — a column was removed, its data type was changed, or a constraint was dropped.

Common causes

1A developer removed a column from a model that has contract: enforced in its YAML definition
2The data type of a contracted column was changed (e.g., INT to VARCHAR) without updating the contract
3A NOT NULL or PRIMARY KEY constraint was removed from a contracted column
4The model's schema.yml was not updated to reflect legitimate schema changes before running dbt

How to fix it

1Step 1: Read the error message to identify which column or constraint was removed or changed.
2Step 2: If the change is intentional: update the contract definition in the model's schema.yml to reflect the new schema, treating it as a versioned breaking change.
3Step 3: If the change was accidental: restore the column or constraint in the model SQL.
4Step 4: Consider using dbt model versioning (v:) to introduce a new version of the model and deprecate the old one, giving consumers time to migrate.
5Step 5: Run dbt parse and dbt compile to validate the updated contract before re-running.

Frequently asked questions

Can I temporarily disable contract enforcement to ship a hotfix?

You can set contract: {enforced: false} in the model YAML, but this is strongly discouraged for production models. Instead, add the new schema state to the contract immediately alongside the code change.

Do data contracts apply to dbt tests as well as models?

Contracts apply to model schema definitions (columns and types). dbt tests (not_null, unique, etc.) are separate and continue to run regardless of contract status.