pola-rs/polars · error · NotImplementedError

schema_mode='overwrite' is not supported for Iceberg tables…

Error message

schema_mode='overwrite' is not supported for Iceberg tables with a sort order

What it means

Sort orders in Iceberg are metadata bound to the schema columns; overwriting the schema could invalidate the defined sort order. Polars raises NotImplementedError when the table has sort order fields and schema_mode='overwrite' is requested.

Solutions

1. Use schema_mode='merge' or None for tables with a sort order
2. Remove the table's sort order metadata, or recreate the table, before overwriting the schema

Example fix

// before
lf.sink_iceberg('db.sorted_t', mode='overwrite', schema_mode='overwrite')
// after
lf.sink_iceberg('db.sorted_t', mode='overwrite', schema_mode=None)

if schema_mode == 'overwrite' and table.sort_order().fields:
    raise NotImplementedError('choose schema_mode merge/None for sorted tables')

try:
    lf.sink_iceberg(target, mode='overwrite', schema_mode=schema_mode)
except NotImplementedError as e:
    if 'sort order' in str(e):
        lf.sink_iceberg(target, mode='overwrite', schema_mode='merge')
    else:
        raise

When it happens

Trigger: Calling sink_iceberg(mode='overwrite', schema_mode='overwrite') against a table whose sort_order() has fields (e.g. table written with an ORDER BY clause).

Common situations: Sinking into a table created with a sort order (write.order.enabled / SQL-created tables) while trying to replace the schema.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• cannot sink to static Iceberg table
• failed to load catalog for
• schema_mode='overwrite' is not supported for partitioned…
• schema_mode='overwrite' requires mode='overwrite'
• sink to Iceberg table with custom location provider

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/4d239831a8eb760a. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/io/iceberg/_sink.py:650

        from pyiceberg.table import TableProperties
        from pyiceberg.utils.properties import property_as_bool, property_as_int

        import polars as pl

        table = self.table()
        table_metadata = table.metadata
        table_properties = table_metadata.properties

        if self.schema_mode == "overwrite" and table.spec().fields:
            msg = "schema_mode='overwrite' is not supported for partitioned Iceberg tables"
            raise NotImplementedError(msg)

        partition_key_exprs = _partition_key_exprs(table, self.source_schema)

        sort_order = table.sort_order()
        if sort_order.fields and self.schema_mode == "overwrite":
            msg = "schema_mode='overwrite' is not supported for Iceberg tables with a sort order"
            raise NotImplementedError(msg)

        if location_provider_impl := table_properties.get(
            TableProperties.WRITE_PY_LOCATION_PROVIDER_IMPL
        ):
            msg = (
                "sink to Iceberg table with custom location provider"
                f" '{location_provider_impl}'"
            )
            raise NotImplementedError(msg)

        object_storage_enabled = property_as_bool(
            table_properties,
            TableProperties.OBJECT_STORE_ENABLED,
            TableProperties.OBJECT_STORE_ENABLED_DEFAULT,
        )
        object_storage_partitioned_paths = (
            property_as_bool(
                table_properties,

View on GitHub (pinned to fe841f959e)