pathwaycom/pathway · error · TypeError

SchemaRegistryHeader.key must be a str, got {type(self.key).

Error message

SchemaRegistryHeader.key must be a str, got {type(self.key).__name__}.

What it means

primary_key only affects how the snapshot output table is maintained in ClickHouse; in the default (append/streaming) output mode it has no effect and is therefore rejected to prevent silently ignored configuration.

Source

Thrown at python/pathway/internals/_io_helpers.py:233

@dataclasses.dataclass(frozen=True)
class SchemaRegistryHeader:
    """
    Represents an additional header to be used in Confluent Schema Registry HTTP requests.

    Args:
        key: The header key.
        value: The header value.

    Returns:
        The constructed header object
    """

    key: str
    value: str

    def __post_init__(self):
        if not isinstance(self.key, str):
            raise TypeError(
                f"SchemaRegistryHeader.key must be a str, got "
                f"{type(self.key).__name__}."
            )
        if not isinstance(self.value, str):
            raise TypeError(
                f"SchemaRegistryHeader.value must be a str, got "
                f"{type(self.value).__name__}."
            )


@dataclasses.dataclass(frozen=True)
class SchemaRegistrySettings:
    """
    Connection settings for the Confluent Schema Registry.

    Args:
        urls: A list of URLs for connecting to the schema registry. If multiple URLs
            are provided, they will be used in the specified order.

View on GitHub (pinned to fa2f74a464)

Solutions

Remove primary_key if you want default append output.
Set output_table_type="snapshot" if you intended keyed, up-to-date rows (and keep primary_key).
For engine-level keying, use pw.Table.with_id / primary_key on the Pathway table itself, not this argument.

Example fix

# before
pw.io.clickhouse.write(t, "db.events", primary_key=t.id)

# after
pw.io.clickhouse.write(t, "db.events")
# or, for keyed snapshots:
pw.io.clickhouse.write(t, "db.events", output_table_type="snapshot", primary_key=t.id)

Defensive patterns

Strategy: validation

Validate before calling

if primary_key is not None:
    assert output_table_type == "snapshot", (
        "primary_key requires output_table_type='snapshot'"
    )
pw.io.clickhouse.write(t, ..., output_table_type=output_table_type, primary_key=primary_key)

Prevention

Keep output_table_type and primary_key in a single dataclass so they stay consistent.
Remember Pathway engine-level keys come from the Table, not from this writer argument.

When it happens

Trigger: Calling pw.io.clickhouse.write(..., primary_key=t.id) while output_table_type is not "snapshot" (default mode).

Common situations: User adds primary_key expecting ClickHouse PRIMARY KEY semantics (which in Pathway are instead configured via table definition) without setting snapshot output; or leftover argument after switching output_table_type back to default.

Related errors

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