pathwaycom/pathway · error · AssertionError

argument {name} has incorrect schema

Error message

argument {name} has incorrect schema

What it means

Pathway's @table_checked decorator (applied via check_types machinery in common.py) validates function arguments and return values against `pw.Table[Schema]` annotations using assert_table_has_schema. When a table's columns/types do not satisfy the annotated schema (considering allow_superset/ignore_primary_keys/allow_subtype per-argument settings), the underlying AssertionError is re-raised as 'argument <name> has incorrect schema', including name="return" for output mismatches.

Source

Thrown at python/pathway/internals/common.py:617

                return value

        allow_superset_dict = convert_to_dict(allow_superset)
        ignore_primary_keys_dict = convert_to_dict(ignore_primary_keys)
        allow_subtype_dict = convert_to_dict(allow_subtype)

        def check_annotation(name, value):
            annotation = annotations.get(name, None)
            if get_origin(annotation) == table.Table and get_args(annotation):
                try:
                    assert_table_has_schema(
                        value,
                        get_args(annotation)[0],
                        allow_superset=allow_superset_dict.get(name, True),
                        ignore_primary_keys=ignore_primary_keys_dict.get(name, True),
                        allow_subtype=allow_subtype_dict.get(name, True),
                    )
                except AssertionError as exc:
                    raise AssertionError(
                        f"argument {name} has incorrect schema"
                    ) from exc

        @wraps(f)
        def wrapper(*args, **kwargs):
            bound_signature = signature.bind(*args, **kwargs)
            for name, arg in bound_signature.arguments.items():
                check_annotation(name, arg)

            return_value = f(*args, **kwargs)
            check_annotation("return", return_value)
            return return_value

        return wrapper

    if func is not None:
        return decorator(func)
    else:

View on GitHub (pinned to fa2f74a464)

Solutions

1. Compare schemas: print the passed table's schema (table.schema) against the annotation's schema and align column names and dtypes.
2. If extra columns are acceptable, rely on/enable allow_superset for that argument; if primary keys differ, adjust ignore_primary_keys settings in the decorator.
3. Fix the producer: declare the schema explicitly on the connector (pw.io.csv.read(..., schema=MySchema)) so dtype inference cannot drift.
4. For name == "return", correct the function body so it produces the annotated output schema.

Example fix

# before
class MySchema(pw.Schema):
    key: str
    value: int

def transform(t: pw.Table[MySchema]) -> pw.Table[MySchema]:
    return t.select(key=t.key)  # missing `value` -> 'argument return has incorrect schema'

# after
def transform(t: pw.Table[MySchema]) -> pw.Table[MySchema]:
    return t.select(key=t.key, value=t.value)

from pathway.internals.table import Table
cols_needed = set(Schema.columns())
cols_have = set(t.schema.columns())
missing = cols_needed - cols_have
assert not missing, f'missing columns {missing}'

def table_matches(table, schema_cls) -> bool:
    try:
        assert_table_has_schema(table, schema_cls)
        return True
    except AssertionError:
        return False

try:
    result = annotated_fn(t)
except AssertionError as e:
    if 'incorrect schema' in str(e):
        print(t.schema); raise

When it happens

Trigger: Calling a function annotated as def f(t: pw.Table[MySchema]) with a table built from a different schema; returning a table lacking required columns or with mismatched dtypes; passing a table where column types are subtypes when allow_subtype=False for that argument.

Common situations: Refactoring shared schemas and forgetting to update one call site; connectors (CSV/kafka) inferring different dtypes than the declared schema; unit tests constructing debug tables with markdown that omit a column.

Related errors

• Failed to detect the region of S3 bucket {bucket!r} (HTTP st
• SchemaRegistryHeader.value must be a str, got {type(self.val
• direction argument of join should be of type asof_join.Direc
• The behavior argument of join should be of type pathway.temp
• The interval argument of a join should be of a type pathway.

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