pathwaycom/pathway · error · TypeError

SchemaRegistryHeader.key must be a str, got

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.

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.

Appendix: 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)