## TL;DR
A renamed upstream column breaks every model that selects the old name: find the new name by diffing the source schema, update the source definition and the affected models, and add a compatibility alias during the transition if other consumers still use the old name. Search the whole project for the old name, because the first compile error is rarely the only reference.

```text
how to fix schema drift failure: column renamed upstream breaks dbt model error
```

## Use this when
- The check or run fails with this symptom: dbt models fail to compile or run after the upstream rename.
- You are working on dbt models breaking after an upstream column rename and the failure repeats on the same data or configuration.
- You need the failing rows, rule, or stage isolated before changing thresholds or code.

## Not for this skill when
- A column that was dropped with no replacement, which needs a redesign of the dependent logic instead.
- The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

## Steps
1. Diff the source table schema against the schema recorded in the dbt source definition and identify the renamed column pair. Verify: the old and new column names are confirmed
2. Search the project, including macros and tests, for every reference to the old column name. Verify: all references are listed
3. Sample the renamed column's values to confirm it carries the same data as the old column did. Verify: the values match the old column's pattern
4. Update the source definition and model references, adding a select alias to the old name if external consumers still depend on it. Verify: models compile against the new name
5. Run dbt build on the affected models and their children and confirm tests pass. Verify: the build and tests are green across the affected subgraph

## Variant phrasings
### schema drift column renamed upstream breaks dbt model
The verbatim rename phrasing.
### dbt model fails column does not exist after rename
The compile-error phrasing users see in dbt output.
### how to handle upstream column rename dbt
The handling phrasing, including transitional aliases.

Compatibility: dbt models on Snowflake, BigQuery, and Postgres with renamed source columns

## Why it happens
Models bind to column names at compile time, so a producer rename is a breaking change even when the data is unchanged. The breakage fans out through every model, test, and exposure that references the name, and partial fixes leave landmines for the next run.

## Edge cases / pitfalls
- Contract tests on sources catch renames at ingestion time rather than at model build time.
- Announce renames with a deprecation window where both names exist. It converts a break into a migration.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_SJGXXCIk__9f_aHSXHgmmA