todo!("Reshape with sub-byte values is not supported when th

Error message

todo!("Reshape with sub-byte values is not supported when the buffer must be recomputed")

What it means

In the CubeCL backend, reshaping a quantized tensor normally works when the buffer layout can be kept; but when the buffer must be recomputed and the quantization scheme packs sub-byte values (Q4S/Q4F/Q2S/Q2F), repacking is unsupported, so `q_reshape` panics with a `todo!`. Sub-byte packed layouts cannot be safely re-chunked without a repacking kernel.

Source

Thrown at crates/burn-cubecl/src/ops/base.rs:458

            ReshapeAction::UpdateStrides {
                strides: scales_strides,
            },
        ) => {
            let qparams = tensor.qparams.as_mut().unwrap();

            qparams.scales.metadata = Metadata::new(shape_scales, scales_strides);
        }
        // Any action to recompute
        (ReshapeAction::Recompute, _) | (_, ReshapeAction::Recompute) => {
            // Rewriting the buffer would have to repack values that share a
            // storage element; a metadata-only reshape leaves the packing alone.
            if !is_unsqueeze
                && matches!(
                    scheme.value,
                    QuantValue::Q4S | QuantValue::Q4F | QuantValue::Q2S | QuantValue::Q2F
                )
            {
                todo!(
                    "Reshape with sub-byte values is not supported when the buffer must be recomputed"
                )
            }

            if scheme.block_size().is_some() && shape_scales.num_elements() > 1 {
                // Original block boundaries no longer align with the layout, would have to be recomputed
                unimplemented!(
                    "Cannot reshape a block-quantized tensor when the reshape requires recomputing the buffer."
                );
            }

            tensor = kernel::into_contiguous(tensor);
            *tensor.meta = Metadata::new(shape, contiguous_strides(&shape_values));

            let qparams = tensor.qparams.as_mut().unwrap();

            let strides = contiguous_strides(&shape_scales);
            qparams.scales.metadata = Metadata::new(shape_scales, strides);

View on GitHub (pinned to d16f7ba2ed)

Solutions

Reshape via dequantize → reshape → re-quantize instead of reshaping the packed tensor.
Use only unsqueeze-style reshapes (adding size-1 dims), which are allowed for sub-byte schemes.
Switch the quantization scheme to a byte-aligned one (e.g. Q8S) if reshaping is required.
Keep the original layout and pad instead of reshaping packed dimensions.

Example fix

// before
let reshaped = q_tensor.reshape([b, h * w]); // Q4S, panics
// after
let f = q_tensor.dequantize();
let reshaped = f.reshape([b, h * w]).quantize(&q_params, QuantScheme::Q4S);

Defensive patterns

Strategy: validation

Validate before calling

fn reshape_safe(scheme: QuantScheme, is_unsqueeze: bool) -> bool {
    is_unsqueeze || !matches!(scheme.value, QuantValue::Q4S | QuantValue::Q4F | QuantValue::Q2S | QuantValue::Q2F)
}

Type guard

fn is_sub_byte(v: &QuantValue) -> bool { matches!(v, QuantValue::Q4S | QuantValue::Q4F | QuantValue::Q2S | QuantValue::Q2F) }

Prevention

Restrict reshapes of sub-byte quantized tensors to unsqueeze-style shape changes.
Dequantize → reshape → requantize for arbitrary reshapes.
Prefer Q8 schemes when layouts must change dynamically.
Check block-size alignment before reshaping quantized activations.

When it happens

Trigger: Calling `.reshape(...)` (or ops that internally reshape) on a quantized tensor with a 4-bit or 2-bit scheme (Q4S, Q4F, Q2S, Q2F) on the CubeCL backend in a case where the reshape is not a plain unsqueeze and forces buffer recomputation (e.g. merging/splitting packed dimensions).

Common situations: Reshaping 4-bit/2-bit quantized model activations or weights between layers; dynamic shape changes in a quantized pipeline; squeezing dimensions that hold packed nibbles.

Related errors

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