pathwaycom/pathway · error · ValueError

{header.name!r} is reserved for the Pathway-injected headers

Error message

{header.name!r} is reserved for the Pathway-injected headers (pathway_time / pathway_diff) and cannot be used as a user header name. Alias the column to another name with `table.select(<new_name>=...)`.

What it means

Raised by MessageQueueOutputFormat.build when a column passed in 'headers' is named 'pathway_time' or 'pathway_diff'. The connector injects commit-time and diff headers under those exact names, so a user header with the same name would be overwritten (or collide) at write time; Pathway rejects it and suggests aliasing the column.

Source

Thrown at python/pathway/io/_utils.py:518

            topic_name_index = None

        # Common part for all formats: obtain key field index and prepare header fields
        if key is not None:
            if (
                allowed_key_types is not None
                and table[key._name]._column.dtype not in allowed_key_types
            ):
                raise ValueError(
                    f"The key column must have one of the following types: {allowed_key_types}"
                )
            key_field_index = cls.add_column_reference_to_extract(
                key, columns_to_extract, extracted_field_indices
            )
        if headers is not None:
            reserved_header_names = {"pathway_time", "pathway_diff"}
            for header in headers:
                if header.name in reserved_header_names:
                    raise ValueError(
                        f"{header.name!r} is reserved for the Pathway-injected "
                        "headers (pathway_time / pathway_diff) and cannot be "
                        "used as a user header name. Alias the column to "
                        "another name with `table.select(<new_name>=...)`."
                    )
                if header.name in header_fields:
                    raise ValueError(
                        f"Duplicate header name {header.name!r}: two columns "
                        "produce a header with the same name. Alias one of "
                        "them to a different name (e.g. via `table.select(...)`) "
                        "to keep both as separate Kafka headers."
                    )
                header_fields[header.name] = cls.add_column_reference_to_extract(
                    header, columns_to_extract, extracted_field_indices
                )

        # Format-dependent parts: handle json and dsv separately
        if format == "json" or format == "dsv":

View on GitHub (pinned to fa2f74a464)

Solutions

1. Alias the column to a different name before passing it: headers=[pw.this.select(header_time=pw.this.pathway_time).header_time] or table.select(emit_time=pw.this.pathway_time).
2. Or drop that column from the headers list if you did not intend to emit it.
3. Reserve the names pathway_time/pathway_diff in your naming conventions.

Example fix

# before
pw.io.kafka.write(t, ..., headers=[pw.this.pathway_time])

# after
t = t.select(*[c for c in t.columns], emit_time=pw.this.pathway_time)
pw.io.kafka.write(t, ..., headers=[pw.this.emit_time])

RESERVED = {'pathway_time', 'pathway_diff'}
bad = [h.name for h in (headers or []) if h.name in RESERVED]
assert not bad, f"reserved header names: {bad}; alias them first"

def headers_avoid_reserved(headers) -> bool:
    return all(h.name not in {'pathway_time', 'pathway_diff'} for h in headers or [])

When it happens

Trigger: pw.io.kafka.write(t, ..., headers=[pw.this.pathway_time, ...]) where the table happens to have a column with that name; tables produced by pw.io.debezium.read or replay modes that carry pathway_time/pathway_diff columns passed wholesale into headers.

Common situations: Feeding connector-internal or framework-reserved column names into Kafka headers; generic code that forwards all table columns as headers without filtering.

Related errors

• Duplicate header name {header.name!r}: two columns produce a
• The table has columns {sorted(conflicting)} which clash with
• Failed to install dependencies
• Column {pseudocolumn} has to contain integers only.
• Column {api.TIME_PSEUDOCOLUMN} cannot contain negative times

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