What causes DF-DELTA-KeyColumnMissed?

The Delta sink's update method is set to 'Upsert' or 'Update' but no key column is listed under 'Key columns' in the sink settings. A key column name was specified but it does not exist in the upstream transformation output (column was renamed, dropped, or never added). Schema drift is enabled and the key column is derived dynamically — but the expression resolves to null or empty for this run

How do I fix DF-DELTA-KeyColumnMissed?

In ADF Studio, open the data flow and click the Delta Lake sink transformation.. Go to the 'Settings' tab and check the update method — if it is 'Upsert' or 'Update', a key column is mandatory.. Under 'Key columns', add the column that uniquely identifies each row (e.g. 'id', 'order_id').. Verify the key column exists in the data flow by clicking 'Inspect' on the node before the sink — the column must appear in that schema.. If using a derived column or schema drift, enable Debug mode, run a data preview on the sink, and confirm the key column is present and non-null in sample rows.

Medium severitydata source

Power BI Refresh Error:
DF-DELTA-KeyColumnMissed

What does this error mean?

The Delta Lake sink is configured for upsert or update, but no key column was specified — or the configured key column name does not exist in the incoming stream. Delta Lake cannot determine which row to match without a key.

Common causes

1The Delta sink's update method is set to 'Upsert' or 'Update' but no key column is listed under 'Key columns' in the sink settings
2A key column name was specified but it does not exist in the upstream transformation output (column was renamed, dropped, or never added)
3Schema drift is enabled and the key column is derived dynamically — but the expression resolves to null or empty for this run

How to fix it

1In ADF Studio, open the data flow and click the Delta Lake sink transformation.
2Go to the 'Settings' tab and check the update method — if it is 'Upsert' or 'Update', a key column is mandatory.
3Under 'Key columns', add the column that uniquely identifies each row (e.g. 'id', 'order_id').
4Verify the key column exists in the data flow by clicking 'Inspect' on the node before the sink — the column must appear in that schema.
5If using a derived column or schema drift, enable Debug mode, run a data preview on the sink, and confirm the key column is present and non-null in sample rows.

Frequently asked questions

Do I need a key column for all Delta Lake sink operations?

No — key columns are only required for 'Upsert' and 'Update'. If you choose 'Insert' or 'Overwrite', no key column is needed.

Can I use a composite key with multiple columns?

Yes — add multiple columns in the Delta sink's 'Key columns' field. The combination of all listed columns is used to match incoming rows for upsert.

The key column exists in my source but still triggers this error — why?

A transformation step may be dropping or renaming the column. Click 'Inspect' on the step immediately before the sink to confirm the key column is still present in the output schema.

Official documentation: https://learn.microsoft.com/en-us/azure/data-factory/data-flow-troubleshoot-guide