pola-rs/polars · error

invalid `return_type`; found {return_type!r}, expected one o

Error message

invalid `return_type`; found {return_type!r}, expected one of 'string', 'frame', 'self', or None

What it means

Raised by DataFrame.glimpse when its `return_type` parameter is not a recognized value. `return_type` controls the return format: None prints the preview to stdout, 'self' prints and returns the original frame, 'frame' returns the preview as a new DataFrame, and 'string' returns the preview text. Booleans are still accepted silently for backwards compatibility with the deprecated `return_as_string` parameter (True -> 'string', False -> None), so only other values reach this ValueError.

Source

Thrown at py-polars/src/polars/dataframe/frame.py:5859

        ┌─────┬──────┬───────┬──────┬──────┬────────────┐
        │ a   ┆ b    ┆ c     ┆ d    ┆ e    ┆ f          │
        │ --- ┆ ---  ┆ ---   ┆ ---  ┆ ---  ┆ ---        │
        │ f64 ┆ i64  ┆ bool  ┆ str  ┆ str  ┆ date       │
        ╞═════╪══════╪═══════╪══════╪══════╪════════════╡
        │ 1.0 ┆ 4    ┆ true  ┆ null ┆ usd  ┆ 2020-01-01 │
        │ 2.8 ┆ 5    ┆ false ┆ b    ┆ eur  ┆ 2021-01-02 │
        │ 3.0 ┆ null ┆ true  ┆ c    ┆ null ┆ 2022-01-01 │
        └─────┴──────┴───────┴──────┴──────┴────────────┘
        """  # noqa: W505
        # handle boolean value from now-deprecated `return_as_string` parameter
        if isinstance(return_type, bool) or return_type is None:  # type: ignore[redundant-expr]
            return_type = "string" if return_type else None  # type: ignore[redundant-expr]
            return_frame = False
        else:
            return_frame = return_type == "frame"
            if not return_frame and return_type not in ("self", "string"):
                msg = f"invalid `return_type`; found {return_type!r}, expected one of 'string', 'frame', 'self', or None"
                raise ValueError(msg)

        # always print at most this number of values (mainly ensures that
        # we do not cast long arrays to strings, which would be slow)
        max_n_values = min(max_items_per_column, self.height)
        schema = self.schema

        def _column_to_row_output(
            col_name: str, dtype: PolarsDataType
        ) -> tuple[str, str, list[str | None]]:
            fn = repr if schema[col_name] == String else str
            values = self[:max_n_values, col_name].to_list()
            if len(col_name) > max_colname_length:
                col_name = col_name[: (max_colname_length - 1)] + "…"
            dtype_str = _dtype_str_repr(dtype)
            if not return_frame:
                dtype_str = f"<{dtype_str}>"
            return (
                col_name,

View on GitHub (pinned to df599052da)

Solutions

1. Set return_type to exactly one of 'string', 'frame', 'self', or omit it (None) for print-only behavior
2. If migrating from the old API: return_as_string=True -> return_type='string', return_as_string=False -> return_type=None (passing the raw bool also still works)
3. Validate/normalize config-driven values against {'string','frame','self',None} before calling glimpse
4. Check case and spelling — the comparison is exact

Example fix

# before
text = df.glimpse(return_type='str')

# after
text = df.glimpse(return_type='string')

VALID = {'string', 'frame', 'self', None}
return_type = return_type if return_type in VALID else 'string'  # or raise your own config error
df.glimpse(return_type=return_type)

def is_glimpse_return_type(v: object) -> bool:
    return v is None or (isinstance(v, str) and v in {'string', 'frame', 'self'})

When it happens

Trigger: Calling df.glimpse(return_type=...) with a value like 'str', 'text', 'Frame', 'df', an int, or any string that does not exactly match 'string'/'frame'/'self' (case-sensitive), e.g. df.glimpse(return_type='str').

Common situations: Upgrading polars to >=1.35.0 where return_as_string was renamed return_type; guessing the new literal when migrating; passing the value from a config variable or CLI flag with a typo; dynamic preview wrappers that forward user input unvalidated.

Related errors

• unexpected input for `strategy`: {strategy!r} Choose one of
• `offset` input for `with_row_index` cannot be {issue}, got {
• cannot use `partition_by` with `maintain_order=False, includ
• cannot specify both `n` and `fraction`
• can only call `.row()` without "index" or "by_predicate" val

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/8a97f2324185807c. Report an issue: GitHub.