pola-rs/polars · error · ValueError

`strict` cannot be used with `how='horizontal_extend'`

Error message

`strict` cannot be used with `how='horizontal_extend'`

What it means

In pl.concat, the deprecated boolean strict parameter is a legacy alias that maps to how='horizontal_extend'. Specifying both strict and how='horizontal_extend' is contradictory and raises ValueError before any concat work happens. The deprecation shim (strict=False maps to horizontal_extend) only applies when how is left at its default.

Source

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

                "is deprecated and will require equal heights in the next breaking "
                "release. "
                "Use `how='horizontal_extend'` to keep the current behavior.",
                version="1.42.1",
            )
            return "horizontal_extend"
        elif strict is False:
            issue_deprecation_warning(
                f"the `strict` parameter for `{function_name}` is deprecated. "
                "Use `how='horizontal_extend'` instead.",
                version="1.42.1",
            )
            return "horizontal_extend"
        else:
            return "horizontal"

    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.

    Parameters
    ----------
    items

View on GitHub (pinned to df599052da)

Solutions

1. Remove strict and keep only how='horizontal_extend'
2. Or, on the legacy path, pass only strict=False and let it map to horizontal_extend
3. Audit wrapper functions that forward **kwargs to concat and strip/clean strict there
4. Use strict=None (or omit it) to mean 'not specified' when you must forward the parameter

Example fix

# before
pl.concat(dfs, how='horizontal_extend', strict=False)

# after
pl.concat(dfs, how='horizontal_extend')
# legacy equivalent (deprecated):
pl.concat(dfs, strict=False)

if how == 'horizontal_extend':
    strict = None  # must not be set alongside how
if strict is not None and how != 'vertical':
    # decide: legacy path or new path, never both
    how, strict = ('horizontal_extend', None) if strict is False else (how, None)
out = pl.concat(items, how=how, strict=strict)

When it happens

Trigger: pl.concat(dfs, how='horizontal_extend', strict=False) — typically half-migrated code that sets the new how but still forwards the old flag; shared wrapper functions that pass **kwargs containing strict into concat.

Common situations: Upgrades around Polars 1.42.1 where strict was deprecated; kwargs-forwarding helpers; copy-paste blending old and new call signatures; defaults like strict=None meaning 'unset' being replaced by a real False.

Related errors

• invalid `return_type`; found {return_type!r}, expected one o
• cannot concat empty list
• DataFrame `how` must be one of {{{allowed}}}, got {how!r}
• LazyFrame `how` must be one of {{{allowed}}}, got {how!r}
• index positions should be smaller than 2^32

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