pola-rs/polars · error · ValueError

must specify either a fill `value` or `strategy`

Error message

must specify either a fill `value` or `strategy`

What it means

Raised by Expr.fill_null when neither a fill `value` nor a fill `strategy` is given. Polars requires exactly one of the two so the operation is well-defined; an empty fill_null() call is almost always a plumbing bug (a value that resolved to None) rather than a meaningful no-op. Like its sibling checks, it raises at expression-construction time.

Source

Thrown at py-polars/src/polars/expr/expr.py:3348

        └──────┴─────┘
        >>> df.with_columns(pl.all().fill_null(pl.all().median()))
        shape: (3, 2)
        ┌─────┬─────┐
        │ a   ┆ b   │
        │ --- ┆ --- │
        │ f64 ┆ f64 │
        ╞═════╪═════╡
        │ 1.0 ┆ 4.0 │
        │ 2.0 ┆ 5.0 │
        │ 1.5 ┆ 6.0 │
        └─────┴─────┘
        """
        if value is not None and strategy is not None:
            msg = "cannot specify both `value` and `strategy`"
            raise ValueError(msg)
        elif value is None and strategy is None:
            msg = "must specify either a fill `value` or `strategy`"
            raise ValueError(msg)
        elif strategy not in ("forward", "backward") and limit is not None:
            msg = "can only specify `limit` when strategy is set to 'backward' or 'forward'"
            raise ValueError(msg)

        if value is not None:
            value_pyexpr = parse_into_expression(value, str_as_lit=True)
            return wrap_expr(self._pyexpr.fill_null(value_pyexpr))
        else:
            assert strategy is not None
            return wrap_expr(self._pyexpr.fill_null_with_strategy(strategy, limit))

    def fill_nan(self, value: int | float | Expr | None) -> Expr:
        """
        Fill floating point NaN value with a fill value.

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

        Parameters

View on GitHub (pinned to df599052da)

Solutions

1. Pass an explicit fill value, e.g. fill_null(0).
2. Or pass a strategy, e.g. fill_null(strategy='mean').
3. If the value is optional by design, branch your code: skip the fill entirely when no value is configured.

Example fix

# before
fill = None
pl.col('a').fill_null(fill)

# after
fill = None
expr = pl.col('a').fill_null(fill) if fill is not None else pl.col('a')

value = None  # from config
assert value is not None or strategy is not None, 'fill_null needs a value or a strategy'

When it happens

Trigger: pl.col('a').fill_null() with no arguments, or fill_null(value=None, strategy=None) when the value comes from a variable that is unexpectedly None.

Common situations: Config-driven pipelines where the fill value is optional and was never set; helper functions that forward **kwargs to fill_null and received neither; copy-paste stubs left with an empty call.

Related errors

• cannot specify both `value` and `strategy`
• strategy {strategy!r} is not supported
• reinterpret requires exactly one of `signed` or `dtype` to b
• cannot specify both `n` and `fraction`
• `new` argument is required if `old` argument is not a Mappin

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