pola-rs/polars · error

cannot unpack series {:?} into matching type {:?}

Error message

cannot unpack series {:?} into matching type {:?}

What it means

unsafe unpack_series_matching_physical_type was called on a Series whose dtype is not physically compatible with the target ChunkedArray type (neither equal nor a known physical/logical pair); the cast would be unsound so it panics.

Source

Thrown at crates/polars-core/src/chunked_array/mod.rs:465

    ///
    /// # Safety
    ///
    /// This is unsafe as the dtype may be incorrect and
    /// is assumed to be correct in other safe code.
    pub(crate) unsafe fn unpack_series_matching_physical_type<'a>(
        &self,
        series: &'a Series,
    ) -> &'a ChunkedArray<T> {
        let series_trait = &**series;
        if self.dtype() == series.dtype() {
            &*(series_trait as *const dyn SeriesTrait as *const ChunkedArray<T>)
        } else {
            use DataType::*;
            match (self.dtype(), series.dtype()) {
                (Int64, Datetime(_, _)) | (Int64, Duration(_)) | (Int32, Date) => {
                    &*(series_trait as *const dyn SeriesTrait as *const ChunkedArray<T>)
                },
                _ => panic!(
                    "cannot unpack series {:?} into matching type {:?}",
                    series,
                    self.dtype()
                ),
            }
        }
    }

    /// Returns an iterator over the lengths of the chunks of the array.
    pub fn chunk_lengths(&self) -> ChunkLenIter<'_> {
        self.chunks.iter().map(|chunk| chunk.len())
    }

    /// A reference to the chunks
    #[inline]
    pub fn chunks(&self) -> &Vec<ArrayRef> {
        &self.chunks
    }

View on GitHub (pinned to 68506541d2)

Solutions

1. Match the series dtype to the type you unpack into (e.g. call `.i32()` only on Int32 series).
2. Cast the series to the target dtype before unpacking.

When it happens

Trigger: This panic/expect fires when execution reaches an unguarded state described by: "cannot unpack series {:?} into matching type {:?}". 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 ("cannot unpack series {:?} into matching type {:?}"). 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/c338dcf645bd1cf9. Report an issue: GitHub.