pathwaycom/pathway · error · ValueError

Column name(s) {sorted(reserved)!r} collide with the reserve

Error message

Column name(s) {sorted(reserved)!r} collide with the reserved {sorted(metadata_columns)!r} metadata columns appended by pw.io.clickhouse.write. Rename the column(s) in your schema before writing.

What it means

Error "Column name(s) {sorted(reserved)!r} collide with the reserved {sorted(metadata_columns)!r} metadata columns appended by pw.io.clickhouse.write. Rename the column(s) in your schema before writing." thrown in pathwaycom/pathway.

Source

Thrown at python/pathway/io/clickhouse/__init__.py:238

    Because the deduplication happens during background merges, query the snapshot
    with ``FINAL`` to always observe the current state:

    .. code-block:: bash

        curl 'http://localhost:8123/?query=SELECT%20name,owner%20FROM%20pets%20FINAL'
    """
    _check_entitlements("clickhouse")

    is_snapshot_mode = output_table_type == SNAPSHOT_OUTPUT_TABLE_TYPE

    column_names = set(table.schema.column_names())
    metadata_columns = (
        {"version", "is_deleted"} if is_snapshot_mode else {"time", "diff"}
    )
    reserved = metadata_columns & column_names
    if reserved:
        raise ValueError(
            f"Column name(s) {sorted(reserved)!r} collide with the reserved "
            f"{sorted(metadata_columns)!r} metadata columns appended by "
            "pw.io.clickhouse.write. Rename the column(s) in your schema before writing."
        )
    key_field_names: list[str] | None = None
    if is_snapshot_mode:
        if primary_key is None or not list(primary_key):
            raise ValueError(
                "output_table_type='snapshot' requires the primary_key parameter: "
                "pass the column(s) that identify each row so the connector can "
                "maintain the current snapshot keyed by them."
            )
        key_field_names = [column.name for column in primary_key]
    elif primary_key is not None:
        raise ValueError(
            "The primary_key parameter is only used with output_table_type='snapshot'; "
            "remove it or set output_table_type='snapshot'."
        )

View on GitHub (pinned to fa2f74a464)

Solutions

1. Rename the colliding columns before writing, e.g. via table.select(new_name=t.old_name).

Example fix

t = t.select(*pw.this.without('time'), ts=t.time); pw.io.clickhouse.write(t, ...)

When it happens

Trigger: Thrown at python/pathway/io/clickhouse/__init__.py:238 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of pathwaycom/pathway@fa2f74a464 (2026-08-15). Data as JSON: /api/errors/d04a7dd82dd12263. Report an issue: GitHub.