tracel-ai/burn · error

Can't store native sub-byte values

Error message

Can't store native sub-byte values

What it means

`dtype_to_elem_type` maps a quantization scheme's store/value into a cubecl `ElemType`. Under `QuantStore::Native`, sub-byte quantized values (Q4F, Q4S, Q2F, Q2S, E2M1) cannot be represented as a native single-byte-plus elem type, so it panics. Sub-byte values must use a packed store mode instead.

Source

Thrown at crates/burn-backend/src/cubecl.rs:100

        DType::U32 => ElemType::UInt(UIntKind::U32),
        DType::U16 => ElemType::UInt(UIntKind::U16),
        DType::U8 => ElemType::UInt(UIntKind::U8),
        DType::Bool(store) => match store {
            BoolStore::Native => ElemType::Bool,
            BoolStore::U8 => ElemType::UInt(UIntKind::U8),
            BoolStore::U32 => ElemType::UInt(UIntKind::U32),
        },
        DType::QFloat(scheme) => match scheme.store {
            QuantStore::Native => match scheme.value {
                QuantValue::Q8F | QuantValue::Q8S => ElemType::Int(IntKind::I8),
                QuantValue::E4M3 => ElemType::Float(FloatKind::E4M3),
                QuantValue::E5M2 => ElemType::Float(FloatKind::E5M2),
                QuantValue::Q4F
                | QuantValue::Q4S
                | QuantValue::Q2F
                | QuantValue::Q2S
                | QuantValue::E2M1 => {
                    panic!("Can't store native sub-byte values")
                }
            },
            QuantStore::PackedU32(_) => ElemType::UInt(UIntKind::U32),
            QuantStore::PackedNative(_) => match scheme.value {
                QuantValue::E2M1 => panic!("Can't store native sub-byte values"),
                other => panic!("{other:?} doesn't support native packing"),
            },
        },
    }
}

/// Convert a burn [`DType`] into the corresponding cubecl [`ElemType`].
///
/// Handles sub-byte packed quantization configurations that cannot be expressed
/// as a plain [`ElemType`] by emitting a direct `ElemType`.
pub fn dtype_to_storage_type(dtype: DType) -> ElemType {
    match dtype {
        DType::QFloat(QuantScheme {

View on GitHub (pinned to d16f7ba2ed)

Solutions

1. Set the scheme's store to `QuantStore::PackedU32` for sub-byte values (Q4/Q2/E2M1) instead of `QuantStore::Native`.
2. Use a byte-or-larger QuantValue (e.g. E4M3, E5M2, Q8F) if you must keep native storage.
3. Fix the quantization configuration so storage mode matches value width before running kernels.

Example fix

// before
let scheme = QuantScheme::new(QuantStore::Native, QuantValue::Q4F, ...);

// after
let scheme = QuantScheme::new(QuantStore::PackedU32(PackingFactor::Uniform8), QuantValue::Q4F, ...);

// validate store/value compatibility before dispatch
fn native_store_ok(scheme: &burn::tensor::QuantScheme) -> bool {
    !matches!(scheme.store, burn::tensor::QuantStore::Native)
        || !matches!(scheme.value,
            burn::tensor::QuantValue::Q4F | burn::tensor::QuantValue::Q4S
            | burn::tensor::QuantValue::Q2F | burn::tensor::QuantValue::Q2S
            | burn::tensor::QuantValue::E2M1)
}

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

When it happens

Trigger: Converting a quantization scheme to elem type (via `dtype_to_storage_type`, `fuse_base`, `create_key`, `generate_reduce_autotune_key`, `compute_input_grad`, `with_bounds`) where the scheme uses `QuantStore::Native` with a 4-bit or 2-bit `QuantValue` (Q4F/Q4S/Q2F/Q2S/E2M1).

Common situations: Configuring quantization with `QuantScheme::from(...).with_store(Native)` and a sub-byte value; loading a quantized checkpoint serialized with packed storage and rebuilding it with native storage; selecting 4-bit quantization (Q4) while forcing native storage in kernel/fusion code.

Related errors

• Quantization scheme is not valid for dtype {other:?}
• {other:?} doesn't support native packing
• float_storage_as_f32: unsupported dtype {:?}
• Expected quantized dtype, got {:?}
• Not a valid DType for tensors.

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