pola-rs/polars · error · ValueError

`strict=False` is no longer supported for `how='horizontal'`

Error message

`strict=False` is no longer supported for `how='horizontal'`. Use `how='horizontal_extend'` to pad shorter frames with `null`.

What it means

ValueError raised by polars' concat normalization when strict=False is combined with how='horizontal'. Padding shorter frames with null on horizontal concatenation was split into a dedicated how='horizontal_extend' mode, so the old strict=False escape hatch is rejected with a pointer to the new mode.

Source

Thrown at py-polars/src/polars/functions/eager.py:53

) -> ConcatMethod:
    """Normalize deprecated horizontal concat arguments."""
    if how == "horizontal":
        match strict:
            case None:
                return "horizontal"
            case True:
                issue_deprecation_warning(
                    f"the `strict` parameter for `{function_name}` is deprecated. "
                    "`how='horizontal'` already requires equal heights; omit `strict`.",
                    version="2.0.0",
                )
                return "horizontal"
            case False:
                msg = (
                    "`strict=False` is no longer supported for `how='horizontal'`. "
                    "Use `how='horizontal_extend'` to pad shorter frames with `null`."
                )
                raise ValueError(msg)

    if how == "horizontal_extend" and strict is not None:
        msg = "`strict` cannot be used with `how='horizontal_extend'`"
        raise ValueError(msg)

    return how


def concat(
    items: Iterable[PolarsType],
    *,
    how: ConcatMethod = "vertical",
    rechunk: bool = False,
    parallel: bool = True,
    strict: bool | None = None,
) -> PolarsType:
    """
    Combine multiple DataFrames, LazyFrames, or Series into a single object.

View on GitHub (pinned to 5d8ebabf11)

Solutions

1. Switch to pl.concat([...], how='horizontal_extend') which pads with nulls
2. Or make frames equal-length/equal-width first (df.hstack, with_columns(pl.lit(None))) if strict horizontal semantics are wanted
3. Remove strict entirely if all frames already match

Example fix

# before
pl.concat([df1, df2], how='horizontal', strict=False)
# after
pl.concat([df1, df2], how='horizontal_extend')

if how == 'horizontal' and strict is False:
    how, strict = 'horizontal_extend', None

When it happens

Trigger: pl.concat([df1, df2], how='horizontal', strict=False) — frames of differing widths or lengths with the legacy flag.

Common situations: Post-upgrade breakage: code that relied on strict=False to align DataFrames of unequal column counts/lengths side by side; old notebooks concatenating batches with ragged schemas.

Related errors

• `strict` cannot be used with `how='horizontal_extend'`
• `{name}` was removed in version {version}
• {func_name!r} received both {param.name!r} and {param.new_na
• the argument {param.name!r} for {func_name!r}{was_deprecated
• the argument {param.name!r} for {func_name!r}{was_deprecated

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