High severityfabric
Power BI Refresh Error:
DELTA_FAILED_TO_MERGE_FIELDS
What does this error mean?
A write or merge operation on a Fabric Lakehouse Delta table failed because the source data's schema is incompatible with the existing Delta table schema. This typically happens when appending data with different column types than the target table, or when performing a MERGE with conflicting field definitions.
Common causes
- 1Appending a DataFrame to a Delta table using .mode('append') when source and target have mismatched data types (e.g., StringType vs. TimestampType)
- 2Loading data from a new source with different column types than the existing Delta table
- 3Schema evolution is disabled on the Delta table (no MERGE SCHEMA option) while the incoming data has a different structure
- 4A MERGE operation where the incoming dataset redefines a field type already present in the target
How to fix it
- 1Cast the source DataFrame columns to match the target Delta table schema before writing: use .cast() to align data types
- 2Run DESCRIBE TABLE <table_name> in a notebook to inspect the current target schema and compare it to the source
Beyond the docs
Common practitioner solutions not covered in the official documentation.
- 1Enable schema evolution by adding .option('mergeSchema', 'true') to the write operation
- 2If schema evolution is intentional, use ALTER TABLE to update the Delta table schema explicitly before the write
- 3Check upstream pipeline or notebook changes that may have altered the column types in the source DataFrame
Official documentation: https://learn.microsoft.com/en-us/fabric/data-engineering/troubleshoot-lakehouse