pola-rs/polars · error

Given array is not a DictionaryArray

Error message

Given array is not a DictionaryArray

What it means

Documented panic of encode_dictionary: the array passed is not a DictionaryArray, so its keys/values cannot be dictionary-encoded for IPC. This is an internal dispatch error — the caller must downcast to DictionaryArray before calling encode_dictionary.

Source

Thrown at crates/polars-arrow/src/io/ipc/write/common.rs:156

            let values = array.as_any().downcast_ref::<MapArray>().unwrap().field();
            let field = field.fields.first().ok_or_else(|| polars_err!(ComputeError: "Invalid IPC field structure: expected nested field but fields vector is empty"))?;
            dictionaries_to_encode(field, values.as_ref(), dictionary_tracker, dicts_to_encode)
        },
    }
}

/// Encode a dictionary array with a certain id.
///
/// # Panics
///
/// This will panic if the given array is not a [`DictionaryArray`].
pub fn encode_dictionary(
    dict_id: i64,
    array: &dyn Array,
    options: &WriteOptions,
) -> PolarsResult<EncodedData> {
    let PhysicalType::Dictionary(key_type) = array.dtype().to_physical_type() else {
        panic!("Given array is not a DictionaryArray")
    };

    match_integer_type!(key_type, |$T| {
        let array: &DictionaryArray<$T> = array.as_any().downcast_ref().unwrap();

        encode_dictionary_values(dict_id, array.values().as_ref(), options)
    })
}

pub fn encode_new_dictionaries(
    field: &IpcField,
    array: &dyn Array,
    options: &WriteOptions,
    dictionary_tracker: &mut DictionaryTracker,
    encoded_dictionaries: &mut Vec<EncodedData>,
) -> PolarsResult<()> {
    let mut dicts_to_encode = Vec::new();
    dictionaries_to_encode(field, array, dictionary_tracker, &mut dicts_to_encode)?;

View on GitHub (pinned to 68506541d2)

Solutions

1. Pass a DictionaryArray to the dictionary-IPC write path; downcast the array to DictionaryArray before calling.
2. If the column is categorical, ensure it is represented as a dictionary-encoded Arrow array before writing.

When it happens

Trigger: This panic/expect fires when execution reaches an unguarded state described by: "Given array is not a DictionaryArray". Typical triggers: unsupported dtype or feature-gated code path reached at runtime, invalid user input or environment variable value, calling API methods in the wrong order or on mismatched types, or data (lengths, offsets, ranges) violating the function's preconditions.

Common situations: Encountered when input data or configuration does not meet the preconditions of the throwing code path ("Given array is not a DictionaryArray"). Common cases: missing Cargo feature flags, mismatched dtypes/lengths between arrays or series, out-of-range temporal values, malformed environment variables, or operations on unsupported/complex nested types.

AI-assisted analysis of pola-rs/polars@68506541d2 (2026-08-19). Data as JSON: /api/errors/bb5634d318c3dd3a. Report an issue: GitHub.