pola-rs/polars · error · TypeError

list.to_struct() got a str instead of a list. hint: pass ['{

Error message

list.to_struct() got a str instead of a list. hint: pass ['{fields}'] instead of '{fields}'

What it means

Identical guard to the array variant but for Expr.list.to_struct: it rejects a plain string passed as fields, since fields must be a sequence of field names or a FieldNaming callable. The message includes a concrete hint showing how to wrap the string in a list.

Source

Thrown at py-polars/src/polars/expr/list.py:1384

        ┌──────┬──────┐
        │ x    ┆ y    │
        │ ---  ┆ ---  │
        │ i64  ┆ i64  │
        ╞══════╪══════╡
        │ 1    ┆ null │
        │ 0    ┆ 1    │
        │ 1    ┆ 0    │
        │ null ┆ null │
        │ null ┆ 1    │
        │ null ┆ null │
        └──────┴──────┘
        """
        if isinstance(fields, str):
            msg = (
                "list.to_struct() got a str instead of a list. "
                f"hint: pass ['{fields}'] instead of '{fields}'"
            )
            raise TypeError(msg)

        return wrap_expr(self._pyexpr.list_to_struct(fields))

    def eval(self, expr: Expr, *, parallel: bool = False) -> Expr:
        """
        Run any polars expression against every lists' elements.

        .. engine-support:: in-memory, streaming, distributed

        Parameters
        ----------
        expr
            Expression to run. Note that you can select an element with `pl.element()`.
        parallel
            Run all expression parallel. Don't activate this blindly.
            Parallelism is worth it if there is enough work to do per thread.

            This likely should not be used in the group by context, because we already

View on GitHub (pinned to 5d8ebabf11)

Solutions

1. Pass a list: .list.to_struct(['f'])
2. Use a callable naming strategy for dynamic field names
3. Normalize helper inputs: fields = [fields] if isinstance(fields, str) else fields

Example fix

# before
pl.col('x').list.to_struct('name')
# after
pl.col('x').list.to_struct(['name'])

fields = [fields] if isinstance(fields, str) else fields

def valid_fields(f) -> bool:
    import collections.abc as abc
    return callable(f) or (isinstance(f, abc.Sequence) and not isinstance(f, str))

When it happens

Trigger: pl.col('x').list.to_struct('f') where 'f' is a str instead of ['f'] or a callable.

Common situations: Migrating list-of-structs code from older polars versions; shared helper functions that accept either a str or list and forward the str directly.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• arr.to_struct() got a str instead of a list. hint: pass ['{f
• expected object supporting the PyCapsule Interface, got {qua
• schema_mode='overwrite' requires mode='overwrite'
• The schema declaration does not match the deserialization
• expected type 'int | str', got {qualified_type_name(item)!r}

AI-assisted analysis of pola-rs/polars@5d8ebabf11 (2026-08-28). Data as JSON: /api/errors/76b9c2e767a3fd43. Report an issue: GitHub.