pathwaycom/pathway · error · TypeError

type annotation of column `{column_name}` does not match col

Error message

type annotation of column `{column_name}` does not match column definition

What it means

A schema column's declared dtype comes from two places: the type annotation and (optionally) the dtype= inside column_definition. If both are given and disagree (after None-defaulting), schema building fails with this TypeError, because Pathway cannot decide which type the column actually has.

Source

Thrown at python/pathway/internals/schema.py:217

                fields[column_name] = column_schema.to_definition()

    columns = {}

    for column_name, annotation in annotations.items():
        col_dtype = dt.wrap(annotation)
        column = fields.pop(column_name, column_definition(dtype=col_dtype))

        if not isinstance(column, ColumnDefinition):
            raise ValueError(
                f"`{column_name}` should be a column definition, found {type(column)}"
            )

        dtype = column.dtype
        if dtype is None:
            dtype = col_dtype

        if col_dtype != dtype:
            raise TypeError(
                f"type annotation of column `{column_name}` does not match column definition"
            )

        column_name = column.name or column_name

        def _get_column_property(property_name: str, default: Any) -> Any:
            match (
                getattr(column, property_name),
                getattr(schema_properties, property_name),
            ):
                case (None, None):
                    return default
                case (None, schema_property):
                    return schema_property
                case (column_property, None):
                    return column_property
                case (column_property, schema_property):
                    if column_property != schema_property:

View on GitHub (pinned to fa2f74a464)

Solutions

1. Make annotation and column_definition(dtype=...) identical, or drop one of them: annotate only (v: int) or define dtype only in column_definition.
2. Prefer the annotation as the single source of truth and use column_definition only for options (default_value, primary_key, description).
3. For complex types (Optional, List, Tuple), double-check both sides use the same pathway type classes.

Example fix

# before
class S(pw.Schema):
    v: int = pw.column_definition(dtype=float)

# after
class S(pw.Schema):
    v: int = pw.column_definition(default_value=0)  # dtype comes from annotation

from pathway.internals import dtype as dt

def annotation_matches_definition(annotation, column) -> bool:
    return column.dtype is None or dt.wrap(annotation) == column.dtype

When it happens

Trigger: class S(pw.Schema): v: int = pw.column_definition(dtype=float) — annotation says int, definition says float. Also mismatched generic parameters like annotation Optional[int] vs dtype=Optional[float], or str vs Any where dtypes compare unequal.

Common situations: Copy-pasting column_definition blocks between differently annotated fields; partially migrating an annotation after changing the dtype= argument.

Related errors

• Unsupported type {input_type}, use pw.DATE_TIME_UTC or pw.DA
• Unsupported type {input_type}, use pw.DURATION
• Unsupported type {input_type!r}.
• `{column_name}` should be a column definition, found {type(c
• definitions of columns {names} lack type annotation

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