pathwaycom/pathway · error · ValueError

All Table.groupby() arguments have to be a ColumnReference.

Error message

All Table.groupby() arguments have to be a ColumnReference.

What it means

The generic branch of groupby()'s argument validation: any positional argument that is neither a ColumnReference nor a string (e.g. int, plain value, arbitrary expression) raises ValueError('All Table.groupby() arguments have to be a ColumnReference.'). Grouping keys must be column references so Pathway can build the grouped universe.

Source

Thrown at python/pathway/internals/table.py:1257

                raise ValueError(
                    "Table.groupby() cannot have id argument when grouping by multiple columns."
                )
            elif args[0]._column != id._column:
                raise ValueError(
                    "Table.groupby() received id argument and is grouped by a single column,"
                    + " but the arguments are not equal.\n"
                    + "Consider using <table>.groupby(id=...), skipping the positional argument."
                )

        for arg in args:
            if not isinstance(arg, expr.ColumnReference):
                if isinstance(arg, str):
                    raise ValueError(
                        f"Expected a ColumnReference, found a string. Did you mean <table>.{arg}"
                        + f" instead of {repr(arg)}?"
                    )
                else:
                    raise ValueError(
                        "All Table.groupby() arguments have to be a ColumnReference."
                    )

        self._check_for_disallowed_types(*args)
        return groupbys.GroupedTable.create(
            table=self,
            grouping_columns=args,
            last_column_is_instance=instance is not None,
            set_id=id is not None,
            sort_by=sort_by,
            _filter_out_results_of_forgetting=_filter_out_results_of_forgetting,
            _skip_errors=_skip_errors,
            _is_window=_is_window,
        )

    @trace_user_frame
    @desugar
    @arg_handler(handler=reduce_args_handler)

View on GitHub (pinned to fa2f74a464)

Solutions

1. Materialize derived keys first: t = t.with_columns(key=t.a + t.b); then t.groupby(t.key)
2. Pass column references only (t.col / pw.this.col); wrap dynamic names with getattr
3. Check for None/unset variables before building the groupby call

Example fix

# before
g = t.groupby(t.a + t.b)  # expression, not a reference -> ValueError

# after
t = t.with_columns(key=t.a + t.b)
g = t.groupby(t.key)

from pathway.internals import expression as expr

def groupby_args_valid(args) -> bool:
    return all(isinstance(a, expr.ColumnReference) for a in args)

from pathway.internals import expression as expr

def is_column_ref(arg) -> bool:
    return isinstance(arg, expr.ColumnReference)

When it happens

Trigger: t.groupby(0); t.groupby(some_derived_expression) instead of first materializing it with with_columns; t.groupby(None) from an unset variable; passing a list object.

Common situations: Index-based grouping ported from pandas; forwarding an expression like t.a + t.b directly instead of a named column; None leaking from optional config.

Related errors

• You cannot use {dep.to_column_expression()} in this reduce s
• You cannot use {dep.to_column_expression()} in this context.
• Expected a ColumnReference, found a string. Did you mean thi
• In JoinResult.groupby() all arguments have to be a ColumnRef
• Table.groupby() cannot have id argument when grouping by mul

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