Asymmetric 3D 'Same' padding is not supported. Use odd kerne

Error message

Asymmetric 3D 'Same' padding is not supported. Use odd kernel sizes for symmetric padding.

What it means

PaddingConfig3d::Same does not support asymmetric padding in any of the three axes (depth, height, width). When calculate_same_padding yields different front/back, top/bottom, or left/right values (which happens with even kernel sizes), the function panics. The fix is to use odd kernel sizes so 'Same' padding splits evenly.

Source

Thrown at crates/burn-nn/src/padding.rs:134

impl PaddingConfig3d {
    /// Calculate symmetric padding for 3D operations.
    /// Returns padding values [depth, height, width] (same for both sides).
    pub(crate) fn calculate_padding_3d(
        &self,
        depth: usize,
        height: usize,
        width: usize,
        kernel_size: &[usize; 3],
        stride: &[usize; 3],
    ) -> [usize; 3] {
        match self {
            Self::Valid => [0, 0, 0],
            Self::Same => {
                let (front, back) = calculate_same_padding(kernel_size[0], stride[0], depth);
                let (top, bottom) = calculate_same_padding(kernel_size[1], stride[1], height);
                let (left, right) = calculate_same_padding(kernel_size[2], stride[2], width);
                if front != back || top != bottom || left != right {
                    panic!(
                        "Asymmetric 3D 'Same' padding is not supported. \
                        Use odd kernel sizes for symmetric padding."
                    )
                }
                [front, top, left]
            }
            Self::Explicit(depth, height, width) => [*depth, *height, *width],
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    // ==================== PaddingConfig1d Tests ====================

    #[test]

View on GitHub (pinned to d16f7ba2ed)

Solutions

Use odd kernel sizes on all three axes (e.g. [3, 3, 3]) so Same padding is symmetric.
Switch to PaddingConfig3d::Valid and apply explicit padding yourself.
Compute the padding manually and pass per-axis padding to a kernel variant that accepts asymmetric padding.

Example fix

// before
let config = Conv3dConfig::new([3, 3, 3], [1, 1, 1]).with_padding(PaddingConfig3d::Same);
// kernel_size [2, 3, 3] would panic; use odd sizes:
let config = Conv3dConfig::new([3, 3, 3], [1, 1, 1]).with_padding(PaddingConfig3d::Same);

Defensive patterns

Strategy: validation

Validate before calling

fn symmetric_same_padding_3d_ok(kernel_size: [usize; 3]) -> bool {
    kernel_size.iter().all(|k| k % 2 == 1) // all three axes must be odd
}

Try / catch

// guard config before building the layer
if !symmetric_same_padding_3d_ok(kernel_size) {
    // fall back to Valid + manual per-axis padding, or reject the config at startup
    panic!("config error: use odd kernels with Same 3D padding");
}

Prevention

Validate 3D conv configs (odd kernels) at startup, not at first forward pass.
Check all three axes (depth, height, width), not just the ones you recently edited.
When porting video/3D models, list every kernel size and verify oddness before enabling Same padding.

When it happens

Trigger: Using PaddingConfig3d::Same with a kernel_size where any of the three entries is even (e.g. [2, 3, 3] or [3, 3, 4]), so one axis produces unequal padding pairs.

Common situations: Building a 3D conv/video model with even kernels; migrating a PyTorch 3D conv config with even kernel sizes into burn; copy-pasting a 2D Same-padding config into a 3D layer.

Related errors

AI-assisted analysis of tracel-ai/burn@d16f7ba2ed (2026-09-05). Data as JSON: /api/errors/857442994e328ae0. Report an issue: GitHub.