pola-rs/polars · error

Map AnyValue payload must be a Struct

Error message

Map AnyValue payload must be a Struct

What it means

A Map AnyValue holds a StructArray whose first field must be the keys column and second the values column. dtype() derives DataType::Map(key, value) from those fields and asserts the payload is a Struct via a let-else; any other payload type is an internal invariant violation and panics.

Solutions

1. Construct Map AnyValues only with a StructArray of exactly [key_field, value_field]; fix the constructor call.
2. Re-read the column through polars' own readers (read_ipc/parquet/json) instead of hand-built arrays.
3. Check s.dtype() on the source Series and verify it is DataType::Map before extracting AnyValues.
4. If hitting this from FFI, validate the incoming Arrow array layout matches the Map spec (entries struct with 2 fields).

Example fix

// before
let av = AnyValue::Map(Arc::new(ListArray::from(...))); // wrong payload
// after
let entries = StructArray::new(
    fields![keys_field, values_field], [keys_arr, values_arr], None,
);
let av = AnyValue::Map(Arc::new(entries));

// before building AnyValue::Map
assert_eq!(entries.data_type(), &ArrowDataType::Struct(...));
assert_eq!(entries.fields().len(), 2); // keys, values

When it happens

Trigger: Calling .dtype() on AnyValue::Map whose inner array is not a StructArray — i.e. a corrupted or wrongly constructed Map value, e.g. built manually with an incorrect array type or produced by an unsafe/FFI path that mislabels the payload.

Common situations: Reading Map columns produced through arrow FFI or custom IO code where the inner array type was not preserved; hand-constructing AnyValue::Map with a non-struct array in bindings/extensions.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• cross join filter holds no keys
• only supported for scalars
• should be f64 scalar
• activate dtype
• activate 'timezones' feature

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

Appendix: source

Thrown at crates/polars-core/src/datatypes/any_value.rs:260

            #[cfg(feature = "dtype-datetime")]
            Datetime(_, tu, tz) => DataType::Datetime(*tu, (*tz).cloned()),
            #[cfg(feature = "dtype-datetime")]
            DatetimeOwned(_, tu, tz) => {
                DataType::Datetime(*tu, tz.as_ref().map(|v| v.as_ref().clone()))
            },
            #[cfg(feature = "dtype-duration")]
            Duration(_, tu) => DataType::Duration(*tu),
            #[cfg(feature = "dtype-categorical")]
            Categorical(_, _) | CategoricalOwned(_, _) => {
                unimplemented!("can not get dtype of Categorical AnyValue")
            },
            #[cfg(feature = "dtype-categorical")]
            Enum(_, _) | EnumOwned(_, _) => unimplemented!("can not get dtype of Enum AnyValue"),
            List(s) => DataType::List(Box::new(s.dtype().clone())),
            #[cfg(feature = "dtype-map")]
            Map(s) => {
                let DataType::Struct(fields) = s.dtype() else {
                    unimplemented!("Map AnyValue payload must be a Struct")
                };
                DataType::Map(
                    Box::new(fields[0].dtype().clone()),
                    Box::new(fields[1].dtype().clone()),
                )
            },
            #[cfg(feature = "dtype-array")]
            Array(s, size) => DataType::Array(Box::new(s.dtype().clone()), *size),
            #[cfg(feature = "dtype-struct")]
            Struct(_, _, fields) => DataType::Struct(fields.to_vec()),
            #[cfg(feature = "dtype-struct")]
            StructOwned(payload) => DataType::Struct(payload.1.clone()),
            #[cfg(feature = "dtype-decimal")]
            Decimal(_, p, s) => DataType::Decimal(*p, *s),
            #[cfg(feature = "object")]
            Object(o) => DataType::Object(o.type_name()),
            #[cfg(feature = "object")]
            ObjectOwned(o) => DataType::Object(o.0.type_name()),

View on GitHub (pinned to fe841f959e)