pathwaycom/pathway · error · ValueError

exactly one of the parameters `schema` or `unpacked_columns`

Error message

exactly one of the parameters `schema` or `unpacked_columns` must be provided

What it means

pw.utils.col.unpack_col expands a composite column (e.g. a Schema-typed or Json column) into separate table columns. It accepts the target field names either via a schema= class or via positional unpacked_columns strings, and requires exactly one of the two: the check `(schema is None) == (len(unpacked_columns) == 0)` raises ValueError when both are provided or neither is.

Source

Thrown at python/pathway/stdlib/utils/col.py:81

    >>> pw.debug.compute_and_print(unpack_table, include_id=False)
    name   | age | pet
    Alice  | 25  | dog
    Bob    | 32  | cat
    Carole | 28  | dog
    >>> class SomeSchema(pw.Schema):
    ...     name: str
    ...     age: int
    ...     pet: str
    >>> unpack_table = pw.utils.col.unpack_col(t2.user, schema=SomeSchema)
    >>> pw.debug.compute_and_print(unpack_table, include_id=False)
    name   | age | pet
    Alice  | 25  | dog
    Bob    | 32  | cat
    Carole | 28  | dog
    """

    if (schema is None) == (len(unpacked_columns) == 0):
        raise ValueError(
            "exactly one of the parameters `schema` or `unpacked_columns` must be provided"
        )

    if schema is not None:
        unpacked_columns = tuple(schema.column_names())
    colrefs = [pw.this[unpacked_column] for unpacked_column in unpacked_columns]
    kw = {colref.name: column[i] for i, colref in enumerate(colrefs)}
    result = column.table.select(**kw)
    if schema is not None:
        result = result.update_types(**schema.typehints())
    return result


@check_arg_types
@trace_user_frame
def unpack_col_dict(
    column: pw.ColumnReference,
    schema: type[pw.Schema],

View on GitHub (pinned to fa2f74a464)

Solutions

1. Provide exactly one: unpack_col(t.user, schema=SomeSchema) OR unpack_col(t.user, 'name', 'age')
2. If using schema=, also get type casting via update_types for free
3. Guard in wrapper code: assert (schema is None) != (not unpacked_columns) before calling

Example fix

# before
unpacked = pw.utils.col.unpack_col(t.user, schema=UserSchema, 'name', 'age')

# after
unpacked = pw.utils.col.unpack_col(t.user, schema=UserSchema)

assert (schema is not None) != (len(unpacked_columns) == 0), 'pass exactly one of schema= or unpacked_columns'

When it happens

Trigger: pw.utils.col.unpack_col(t.user, schema=SomeSchema, 'name', 'age') (both given); pw.utils.col.unpack_col(t.user) with no schema and no column names (neither given).

Common situations: Copy-pasting a call that evolved from positional names to a schema without removing the old arguments; refactoring tutorials where the schema argument is deleted but no replacement names are added; passing unpacked_columns as a list that is accidentally empty.

Related errors

• 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.
• Join received extra kwargs. You probably want to use TableLi
• Expected a ColumnReference, found a string. Did you mean thi

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