pola-rs/polars · error · InvalidArgument

map keys cannot be a nested dtype, got {key!r}

Error message

map keys cannot be a nested dtype, got {key!r}

What it means

The Hypothesis-based parametric testing strategy for Map columns refuses keys whose dtype is nested (List, Struct, another Map, etc.), because Polars Map keys must be scalar/primitive dtypes. It raises InvalidArgument naming the offending key dtype.

Source

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

    Parameters
    ----------
    key
        The data type of the keys. Cannot be nested, since keys become Python dict keys
        and those must be hashable.
    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,
    )

View on GitHub (pinned to 68506541d2)

Solutions

1. Use a primitive key dtype, e.g. pl.Map(pl.String, pl.Int64) or pl.Map(pl.Int32, ...).
2. Check the argument order — you may have passed the nested dtype as key when it was meant as value.
3. If nested keys are semantically required, model the data as List(Struct({key, value})) instead of Map.

Example fix

// before
st = maps(key=pl.List(pl.Int64), value=pl.Int64)
// after
st = maps(key=pl.Int64, value=pl.List(pl.Int64))

import polars as pl
def validate_map_key(dtype):
    key = dtype.key if isinstance(dtype, pl.Map) else dtype
    if key.is_nested():
        raise InvalidArgument(f"map key must be primitive, got {key}")
    return key

try:
    st = maps(key=key, value=value)
except InvalidArgument as e:
    if "nested dtype" in str(e):
        st = maps(key=pl.String, value=value)
    else:
        raise

When it happens

Trigger: Calling the `maps()` data strategy (directly or via data() / pl.testing parametric strategies) with key= a nested dtype such as pl.List(pl.Int64), pl.Struct(...), or pl.Map(...).

Common situations: Auto-generating strategies from a schema where a Map's key dtype was itself nested; writing property-based tests with deliberately exotic dtypes; typos building the Map dtype (swapping key and value arguments so a nested value lands in key).

Related errors

• map keys cannot be Null; specify a key type, e.g. `pl.Map(pl
• `format` must be one of {{'binary', 'json'}}, got {format!r}
• `time_unit` must be one of {'ns', 'us', 'ms', 's', 'd'}, got
• use of `how='outer_coalesce'` should be replaced with `how='
• Map requires a key and a value type, e.g. `pl.Map(pl.String,

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