What causes DELTA_ILLEGAL_COLUMN_NAME?

A column name contains spaces, dots, semicolons, curly braces, parentheses, or other special characters not allowed by Delta. Source data (JSON, CSV, Parquet from an external system) contains column names with illegal characters that are automatically inferred. A dbt model or SQL transformation produces column aliases containing special characters. Autoloader schema inference picked up a JSON field name with a dot (e.g., `address.city`) as a flat column name

How do I fix DELTA_ILLEGAL_COLUMN_NAME?

Rename the offending column before writing: use a select alias or a rename transformation to replace illegal characters.. Enable Delta Column Mapping (requires reader/writer version 2/5+): `ALTER TABLE t SET TBLPROPERTIES ('delta.columnMapping.mode' = 'name')` — this allows column names with spaces and special characters.. For Autoloader JSON sources, use `cloudFiles.inferColumnTypes = false` and define the schema explicitly to control column names.. If the illegal character is a dot, consider whether the field should be a nested struct rather than a flat column.

Medium severitysql

Power BI Refresh Error:
DELTA_ILLEGAL_COLUMN_NAME

What does this error mean?

A column name in the Delta table schema contains characters that are not permitted by Delta Lake. The write or schema evolution operation is rejected.

Common causes

1A column name contains spaces, dots, semicolons, curly braces, parentheses, or other special characters not allowed by Delta
2Source data (JSON, CSV, Parquet from an external system) contains column names with illegal characters that are automatically inferred
3A dbt model or SQL transformation produces column aliases containing special characters
4Autoloader schema inference picked up a JSON field name with a dot (e.g., `address.city`) as a flat column name

How to fix it

1Rename the offending column before writing: use a select alias or a rename transformation to replace illegal characters.
2Enable Delta Column Mapping (requires reader/writer version 2/5+): `ALTER TABLE t SET TBLPROPERTIES ('delta.columnMapping.mode' = 'name')` — this allows column names with spaces and special characters.
3For Autoloader JSON sources, use `cloudFiles.inferColumnTypes = false` and define the schema explicitly to control column names.
4If the illegal character is a dot, consider whether the field should be a nested struct rather than a flat column.

Frequently asked questions

What characters are forbidden in Delta column names without Column Mapping?

Spaces, commas, semicolons, curly braces `{}`, parentheses `()`, equals `=`, newlines, and tab characters are not allowed. Dots in flat column names are also problematic.