pola-rs/polars · error

should not fail

Error message

should not fail

What it means

vstack_mut_unchecked appends each column of other to self without schema validation, trusting the caller. Series::append can still fail (mismatched dtypes, memory errors); the with_context(...).expect("should not fail") converts that error into a panic naming the failing column.

Source

Thrown at crates/polars-core/src/frame/mod.rs:688

        Ok(self)
    }

    /// Concatenate a [`DataFrame`] to this [`DataFrame`]
    ///
    /// If many `vstack` operations are done, it is recommended to call [`DataFrame::align_chunks_par`].
    ///
    /// # Panics
    /// Panics if the schema's don't match.
    pub fn vstack_mut_unchecked(&mut self, other: &DataFrame) -> &mut Self {
        let new_height = usize::checked_add(self.height(), other.height()).unwrap();

        unsafe { self.columns_mut_retain_schema() }
            .iter_mut()
            .zip(other.columns())
            .for_each(|(left, right)| {
                left.append(right)
                    .with_context(|| format!("failed to vstack column '{}'", right.name()))
                    .expect("should not fail");
            });

        unsafe { self.set_height(new_height) };

        self
    }

    /// Concatenate a [`DataFrame`] to this [`DataFrame`]
    ///
    /// If many `vstack` operations are done, it is recommended to call [`DataFrame::align_chunks_par`].
    ///
    /// # Panics
    /// Panics if the schema's don't match.
    pub fn vstack_mut_owned_unchecked(&mut self, other: DataFrame) -> &mut Self {
        let new_height = usize::checked_add(self.height(), other.height()).unwrap();

        unsafe { self.columns_mut_retain_schema() }
            .iter_mut()

View on GitHub (pinned to 68506541d2)

Solutions

1. Switch to the checked API: df.vstack(&other)? which returns a PolarsResult instead of panicking
2. Verify schemas before the unchecked call: self.schema() and other.schema() must have identical dtypes per column
3. Cast mismatching columns to the target dtype before vstacking

Example fix

// before
df.vstack_mut_unchecked(&other); // panics on dtype drift

// after
df.vstack(&other).map_err(|e| format!("vstack failed: {e}"))?;

fn schemas_match(a: &DataFrame, b: &DataFrame) -> bool {
    a.schema() == b.schema()
}

When it happens

Trigger: Calling DataFrame::vstack_mut_unchecked (or a caller of it) where left/right column dtypes differ for a column name, e.g. Int32 vs Int64, String vs Categorical, different time zones; or when append hits an allocation failure.

Common situations: Performance-tuned code skipping the checked vstack after schemas drifted (a cast added upstream, a CSV re-inferred different integer widths); concatenating frames produced by different readers or polars versions.

Related errors

• The schema declaration does not match the deserialization
• not implemented
• length to fit in `usize`
• offset to fit in `usize`
• Offset to fit in `usize`

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