pola-rs/polars · error · ValueError

cannot infer dtype from {original_value!r} string value

Error message

cannot infer dtype from {original_value!r} string value

What it means

Raised by polars.io.database._inference when schema inference cannot map a string cell value to any known dtype and raise_unmatched is set. During read_database row-level fallback, object/string values are pattern-matched against recognised formats (numbers, dates, times, intervals, booleans); an unrecognisable value aborts inference rather than guessing.

Source

Thrown at py-polars/src/polars/io/database/_inference.py:204

    # temporal dtypes
    elif value.startswith(("DATETIME", "TIMESTAMP")) and not (value.endswith("[D]")):
        if any((tz in value.replace(" ", "")) for tz in ("TZ", "TIMEZONE")):
            if "WITHOUT" not in value:
                return None  # there's a timezone, but we don't know what it is
        unit = timeunit_from_precision(modifier) if modifier else "us"
        dtype = Datetime(time_unit=(unit or "us"))  # type: ignore[arg-type]
    else:
        value = re.sub(r"\d", "", value)
        if value in ("INTERVAL", "TIMEDELTA", "DURATION"):
            dtype = Duration
        elif value == "DATE":
            dtype = Date
        elif value == "TIME":
            dtype = Time

    if not dtype and raise_unmatched:
        msg = f"cannot infer dtype from {original_value!r} string value"
        raise ValueError(msg)

    return dtype


def dtype_from_cursor_description(
    description: tuple[Any, ...],
) -> PolarsDataType | None:
    """Attempt to infer Polars dtype from database cursor description `type_code`."""
    type_code, _disp_size, internal_size, precision, scale, *_ = description
    dtype: PolarsDataType | None = None

    if isclass(type_code):
        # python types, eg: int, float, str, etc
        with suppress(TypeError):
            dtype = parse_py_type_into_dtype(type_code)  # type: ignore[arg-type]

    elif isinstance(type_code, str):
        # database/sql type names, eg: "VARCHAR", "NUMERIC", "BLOB", etc

View on GitHub (pinned to df599052da)

Solutions

Pass schema_overrides={'col': pl.String} (or the correct dtype) for the offending column so inference is bypassed
Load the column as String and parse/cast afterwards with str.strptime / str.to_* and errors-facing logic
Clean or normalise the source values, or select CAST(... AS VARCHAR) on the database side to make the type explicit

Example fix

# before
df = pl.read_database("SELECT metadata_col, val FROM t", conn)  # inference fails on odd string

# after
df = pl.read_database(
    "SELECT metadata_col, val FROM t", conn,
    schema_overrides={"metadata_col": pl.String},
)

Defensive patterns

Strategy: validation

Validate before calling

import polars as pl

# force string loading for free-form text columns, bypassing inference
OVERRIDE = {c: pl.String for c in likely_untyped_columns}
df = pl.read_database(query, conn, schema_overrides=OVERRIDE)

Try / catch

try:
    df = pl.read_database(query, conn)
except ValueError as e:
    if "cannot infer dtype" in str(e):
        df = pl.read_database(query, conn, schema_overrides={col: pl.String for col in all_cols})
    else:
        raise

Prevention

Always supply schema_overrides for columns with driver-specific or custom-serialised values
Load unknown columns as pl.String first, then parse with strptime/to_integer in polars
Cast exotic types to VARCHAR in the SQL itself so types are explicit

When it happens

Trigger: read_database() returning row-level data where a column contains string values that match no supported pattern (custom serialisations, UUIDs with odd formatting, driver-specific type names, exotic interval literals); raise_unmatched=True is set when the value would otherwise silently become String and the caller asked for strict inference.

Common situations: Reading from databases whose drivers stringify unusual types (Oracle intervals, MSSQL sql_variant, PG enums/circles); schema_overrides not supplied for columns holding non-standard textual data; data with mixed/malformed values in a column expected to be typed.

Related errors

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