pola-rs/polars · error · TypeError

expected 'time' to be a Python time or Polars expression…

Error message

expected 'time' to be a Python time or Polars expression, found {qualified_type_name(time)!r}

What it means

Expr.dt.combine joins a date column with a time to produce a datetime; the time argument must be a datetime.time instance or a polars Expr. Anything else raises TypeError naming the qualified type found.

Solutions

1. Wrap the value: time=dt.time(12, 30) or pl.lit('12:30').str.to_time() then pass the Expr
2. Parse string times first with str.to_time() and pass that expression
3. Extract the time part if you have a datetime: combine(dt_obj.time())
4. Add an isinstance(time, (dt.time, pl.Expr)) assertion before the call

Example fix

// before
pl.col('date').dt.combine('12:30')
// after
pl.col('date').dt.combine(dt.time(12, 30))

import datetime as dt, polars as pl
if not isinstance(time, (dt.time, pl.Expr)):
    raise TypeError('time must be datetime.time or pl.Expr')

import datetime as dt
import polars as pl
def is_time_or_expr(x) -> bool:
    return isinstance(x, (dt.time, pl.Expr))

try:
    e = col.dt.combine(t)
except TypeError as e:
    if 'expected .time. to be' in str(e):
        t = pl.lit(str(t)).str.to_time() if isinstance(t, str) else dt.time(t.hour, t.minute)
        e = col.dt.combine(t)
    else:
        raise

When it happens

Trigger: Calling pl.col('date').dt.combine('12:30'), combine(datetime.datetime(...)), or passing a string/None instead of dt.time or a pl.Expr.

Common situations: Passing time as a string from config ('09:00:00'); using datetime.datetime instead of datetime.time; passing an integer hour; confusion with pandas' combine which takes DatetimeIndex-like args.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• arr.to_struct() got a str instead of a list. hint: pass
• cannot call `map_groups` when filtering groups with `having`
• cannot call `map_groups` when grouping by an expression
• cannot call `map_groups` when grouping by named expressions
• cannot set Series of dtype

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/64090d79f411dd2c. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/expr/datetime.py:563

        ...     [
        ...         pl.col("dtm").dt.combine(pl.col("tm")).alias("d1"),
        ...         pl.col("dt").dt.combine(pl.col("tm")).alias("d2"),
        ...         pl.col("dt").dt.combine(time(4, 5, 6)).alias("d3"),
        ...     ]
        ... )
        shape: (2, 3)
        ┌─────────────────────────┬─────────────────────────┬─────────────────────┐
        │ d1                      ┆ d2                      ┆ d3                  │
        │ ---                     ┆ ---                     ┆ ---                 │
        │ datetime[μs]            ┆ datetime[μs]            ┆ datetime[μs]        │
        ╞═════════════════════════╪═════════════════════════╪═════════════════════╡
        │ 2022-12-31 01:02:03.456 ┆ 2022-10-10 01:02:03.456 ┆ 2022-10-10 04:05:06 │
        │ 2023-07-05 07:08:09.101 ┆ 2022-07-05 07:08:09.101 ┆ 2022-07-05 04:05:06 │
        └─────────────────────────┴─────────────────────────┴─────────────────────┘
        """
        if not isinstance(time, (dt.time, pl.Expr)):
            msg = f"expected 'time' to be a Python time or Polars expression, found {qualified_type_name(time)!r}"
            raise TypeError(msg)
        time_pyexpr = parse_into_expression(time)
        return wrap_expr(self._pyexpr.dt_combine(time_pyexpr, time_unit))

    def to_string(self, format: str | None = None) -> Expr:
        """
        Convert a Date/Time/Datetime column into a String column with the given format.

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

        .. versionchanged:: 1.15.0
            Added support for the use of "iso:strict" as a format string.
        .. versionchanged:: 1.14.0
            Added support for the `Duration` dtype, and use of "iso" as a format string.

        Parameters
        ----------
        format
            * Format to use, refer to the `chrono strftime documentation

View on GitHub (pinned to fe841f959e)