pola-rs/polars · error · InvalidArgument

map keys cannot be Null; specify a key type, e.g. `pl.Map(pl

Error message

map keys cannot be Null; specify a key type, e.g. `pl.Map(pl.String, pl.Int64)`

What it means

The parametric `maps()` strategy also refuses Null as the Map key dtype. A bare pl.Map carries no key type; rather than generating useless {None: None} data, the strategy raises InvalidArgument telling you to specify a concrete key type.

Source

Thrown at py-polars/src/polars/testing/parametric/strategies/data.py:393

    value
        The data type of the values.
    min_size
        The minimum number of entries in a map.
    max_size
        The maximum number of entries in a map.
    allow_null
        Allow nulls as possible values.
    **kwargs
        Additional arguments that are passed to nested data generation strategies.
    """
    if key.is_nested():
        msg = f"map keys cannot be a nested dtype, got {key!r}"
        raise InvalidArgument(msg)
    if key == Null:
        # Reached via a bare `pl.Map`, which cannot say what its keys are. Generating
        # `{None: None}` would be worse than refusing: Map keys are never null.
        msg = "map keys cannot be Null; specify a key type, e.g. `pl.Map(pl.String, pl.Int64)`"
        raise InvalidArgument(msg)
    if max_size is None:
        max_size = _DEFAULT_MAP_SIZE_LIMIT

    inner_kwargs = {
        k: v for k, v in kwargs.items() if k not in ("min_size", "max_size")
    }
    return st.dictionaries(
        data(key, allow_null=False, **inner_kwargs),
        data(value, allow_null=allow_null, **inner_kwargs),
        min_size=min_size,
        max_size=max_size,
    )


def nulls() -> SearchStrategy[None]:
    """Create a strategy for generating null values."""
    return st.none()

View on GitHub (pinned to 68506541d2)

Solutions

Specify key and value types in the dtype: pl.Map(pl.String, pl.Int64), then pass that to the strategy.
If the dtype comes from an external schema, fill in the Map parameters before generating strategies.
Choose a stable key dtype matching your real data (String, Int64, etc.).

Example fix

// before
st = data(dtype=pl.Map)
// after
st = data(dtype=pl.Map(pl.String, pl.Int64))

Defensive patterns

Strategy: validation

Validate before calling

import polars as pl
def require_parameterized_map(dtype):
    if isinstance(dtype, pl.Map):
        key = dtype.key
    else:
        key = None
    if key is None or key == pl.Null:
        raise InvalidArgument("specify key/value types, e.g. pl.Map(pl.String, pl.Int64)")
    return dtype

Try / catch

try:
    st = data(dtype=dtype)
except InvalidArgument as e:
    if "map keys cannot be Null" in str(e):
        st = data(dtype=pl.Map(pl.String, pl.Int64))
    else:
        raise

Prevention

Never declare bare pl.Map in schemas; always parameterize
Fill in Map parameters when importing dtypes from external schema formats
Choose a concrete, stable key dtype matching production data

When it happens

Trigger: Using data()/maps() for a column typed bare pl.Map (no key/value parameters), or explicitly passing key=pl.Null to maps().

Common situations: Property-based tests driven by a schema that declares `pl.Map` without parameters; dtype round-trip tests where parameterized Map info was lost during serialization.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of pola-rs/polars@68506541d2 (2026-09-10). Data as JSON: /api/errors/2e68363a612519f4. Report an issue: GitHub.