pola-rs/polars · error

invalid Map dtype in `Series::full_null`

Error message

invalid Map dtype in `Series::full_null`

What it means

Series::full_null constructs an all-null Series of a given dtype. When the requested dtype is Map (feature `dtype-map`), it first validates the Map's inner/entry dtypes via ensure_valid_map_dtypes; if that returns Err, the code panics because full_null cannot return a Result. It means the Map dtype supplied is structurally invalid (e.g. bad inner key/value dtypes).

Solutions

1. Inspect the Map dtype's inner key/value types and construct it with valid entry dtypes (valid value types, list-of-entries structure)
2. Avoid hand-building DataType::Map; obtain the dtype from an existing valid Map column and reuse it
3. If you only need a null placeholder, use a supported dtype (e.g. List) or wrap full_null's dtype construction so invalid maps are rejected earlier
4. Verify the feature set: `dtype-map` is unstable; consider avoiding Map in schemas that get all-null materialized

fn map_dtype_is_valid(dt: &DataType) -> bool {
    match dt {
        DataType::Map(_, _) => true, // tighten: validate entry/value dtypes
        _ => true,
    }
}
if !map_dtype_is_valid(dtype) { return Err("invalid Map dtype for full_null"); }

fn is_map(dt: &DataType) -> bool { matches!(dt, DataType::Map(_, _)) }

When it happens

Trigger: Calling Series::full_null(name, size, &DataType::Map(...)) with an invalid inner dtype combination, or propagating a malformed Map dtype (e.g. from deserialization or a hand-constructed DataType) into full_null.

Common situations: Building empty/all-null frames with a Map column whose dtype was constructed manually or round-tripped from a source with unsupported entry types; dtype mismatches after schema stitching.

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

• activate dtype
• activate feature dtype-duration
• cannot create duration from other type. dtype
• cannot create time from other type. dtype
• date not implemented for

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

Appendix: source

Thrown at crates/polars-core/src/series/ops/null.rs:20

use polars_arrow::offset::OffsetsBuffer;
use polars_buffer::Buffer;

#[cfg(feature = "object")]
use crate::chunked_array::object::registry::get_object_builder;
use crate::prelude::*;

impl Series {
    /// Create a Series of `size` null values with the requested dtype.
    ///
    /// # Panics
    /// Panics if `dtype` contains an invalid Map dtype.
    pub fn full_null(name: PlSmallStr, size: usize, dtype: &DataType) -> Self {
        // Separate from the `match` below, because it only peels off a single layer of
        // nesting.
        #[cfg(feature = "dtype-map")]
        dtype
            .ensure_valid_map_dtypes()
            .expect("invalid Map dtype in `Series::full_null`");

        // match the logical types and create them
        match dtype {
            DataType::List(inner_dtype) => {
                ListChunked::full_null_with_dtype(name, size, inner_dtype).into_series()
            },
            #[cfg(feature = "dtype-array")]
            DataType::Array(inner_dtype, width) => {
                ArrayChunked::full_null_with_dtype(name, size, inner_dtype, *width).into_series()
            },
            #[cfg(feature = "dtype-categorical")]
            dt @ (DataType::Categorical(_, _) | DataType::Enum(_, _)) => {
                with_match_categorical_physical_type!(dt.cat_physical().unwrap(), |$C| {
                    CategoricalChunked::<$C>::full_null_with_dtype(
                        name,
                        size,
                        dtype.clone()
                    )

View on GitHub (pinned to fe841f959e)