pola-rs/polars · error · TypeError

dtypes must be fully-specified, got

Error message

dtypes must be fully-specified, got: {tp!r}

What it means

pl.Schema requires fully-specified DataType instances. Parameterized dtypes given as classes without arguments (e.g. pl.List, pl.Decimal, pl.Array) are rejected because required parameters are missing.

Solutions

1. Fully specify the dtype: pl.List(pl.Int64), pl.Array(pl.Float64, 3), pl.Decimal(38, 10)
2. Use scalars like pl.Int64 directly (they don't need args)
3. Instantiate with required args before assigning into the schema

Example fix

// before
pl.Schema({"a": pl.List})
// after
pl.Schema({"a": pl.List(pl.Int64)})

def fully_specified(tp) -> bool:
    return isinstance(tp, pl.DataType)
pl.Schema({k: v if fully_specified(v) else v() for k, v in raw.items()})

def is_concrete_dtype(tp) -> bool:
    return isinstance(tp, pl.DataType)

try:
    schema = pl.Schema(raw)
except TypeError as e:
    schema = pl.Schema({k: v() for k, v in raw.items()})

When it happens

Trigger: pl.Schema({"a": pl.List}) or pl.Schema({"d": pl.Decimal}) — passing the bare class for a nested/decimal/parameterized dtype; also via __setitem__ (schema["a"] = pl.List).

Common situations: Typing dtypes from memory without parameters; generic schemas where nested types were left unspecified.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• cannot compare datetime.datetime to Series of type
• cannot construct PySeries for type
• cannot convert DataFrame to
• cannot convert List column
• cannot convert Python type

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

Appendix: source

Thrown at py-polars/src/polars/schema.py:56

    from polars._dependencies import pyarrow as pa


def _required_init_args(tp: DataTypeClass) -> bool:
    return bool(tp.__annotations__)


BaseSchema = OrderedDict[str, DataType]
SchemaInitDataType: TypeAlias = DataType | DataTypeClass | PythonDataType

__all__ = ["Schema"]


def _check_dtype(tp: DataType | DataTypeClass) -> DataType:
    if not isinstance(tp, DataType):
        # note: if nested/decimal, or has signature params, this implies required args
        if tp.is_nested() or tp.is_decimal() or _required_init_args(tp):
            msg = f"dtypes must be fully-specified, got: {tp!r}"
            raise TypeError(msg)
        tp = tp()
    return tp  # type: ignore[return-value]


def _is_arrow_schema_exportable(obj: Any) -> TypeIs[ArrowSchemaExportable]:
    return hasattr(obj, "__arrow_c_schema__")


class Schema(BaseSchema):
    """
    Ordered mapping of column names to their data type.

    Parameters
    ----------
    schema
        The schema definition given by column names and their associated
        Polars data type. Accepts a mapping, or an iterable of tuples, or any
        object implementing the  `__arrow_c_schema__` PyCapsule interface

View on GitHub (pinned to fe841f959e)