dbt snapshot "missing ... unique_key" configuration error in CI

By Daniel Zoghalchali·Latchkey

A dbt snapshot requires a unique_key to identify rows across runs, and this snapshot did not declare one. Without it dbt cannot detect which records changed, so it refuses to run the snapshot.

What this error means

dbt snapshot fails with "Runtime Error ... 'unique_key' is a required property" or "Snapshot X is missing a required configuration: unique_key".

Runtime Error
  Snapshot 'orders_snapshot' (snapshots/orders_snapshot.sql) is missing a
  required configuration: 'unique_key'

Common causes

The snapshot config omits unique_key

The snapshot block declares a strategy but no unique_key, so dbt has no column to identify rows across runs.

A misplaced config outside the snapshot block

The unique_key is set in the wrong scope (not inside the snapshot config), so dbt does not see it for this snapshot.

How to fix it

Add unique_key to the snapshot config

1. Choose the column (or columns) that uniquely identify a record.
2. Set unique_key in the snapshot config block or YAML.
3. Run dbt snapshot --select the_snapshot to confirm.

{% snapshot orders_snapshot %}
{{ config(
    target_schema='snapshots',
    unique_key='order_id',
    strategy='timestamp',
    updated_at='updated_at'
) }}
select * from {{ source('shop', 'orders') }}
{% endsnapshot %}

Use a surrogate key for composite identity

If no single column is unique, build a surrogate key and use it as unique_key.

How to prevent it

• Always set unique_key on every snapshot.
• Use a surrogate key when identity spans multiple columns.
• Run dbt snapshot in CI so config gaps surface before deploy.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation