tracel-ai/burn · error

Can't store native sub-byte values

Error message

Can't store native sub-byte values

What it means

Sub-byte quantized values (Q4, Q2, E2M1) cannot be stored in Native mode, which stores one value per element slot in memory. They must be packed (PackedU32 or PackedNative). Attempting to allocate a native-stored tensor with one of these value types panics.

Source

Thrown at crates/burn-cubecl/src/ops/qtensor.rs:102

    let data_size = match scheme.store {
        QuantStore::PackedU32(_) => {
            if !shape_last.is_multiple_of(num_quants) {
                panic!("Can't store in u32")
            }
            shape_value[rank - 1] = shape_last.div_ceil(num_quants);
            size_of::<u32>()
        }
        QuantStore::Native => match scheme.value {
            QuantValue::Q8F | QuantValue::Q8S | QuantValue::E4M3 | QuantValue::E5M2 => {
                size_of::<i8>()
            }
            QuantValue::Q4F
            | QuantValue::Q4S
            | QuantValue::Q2F
            | QuantValue::Q2S
            | QuantValue::E2M1 => {
                panic!("Can't store native sub-byte values")
            }
        },
        QuantStore::PackedNative(_) => match scheme.value {
            QuantValue::E2M1 => size_of::<e2m1x2>(),
            other => panic!("{other:?} doesn't support native packing"),
        },
    };

    let scales_dtype = match scheme.scale_dtype() {
        ScaleDtype::F32 => DType::F32,
        ScaleDtype::F16 => DType::F16,
        ScaleDtype::BF16 => DType::BF16,
        // Represented by U8 and reinterpreted in the kernel
        ScaleDtype::UE8M0 | ScaleDtype::UE4M3 => DType::U8,
    };

    let scales_shape = params_shape(&shape, &scheme);
    let data_desc = MemoryLayoutDescriptor::new(alloc_kind, shape_value.clone(), data_size);

View on GitHub (pinned to d16f7ba2ed)

Solutions

1. Set the scheme's store to QuantStore::PackedU32 or PackedNative for sub-byte value types
2. Or switch the value type to a byte-sized one (Q8F/Q8S/E4M3/E5M2) to keep Native storage
3. Validate the store/value combination when constructing QuantScheme

Example fix

// before
let scheme = QuantScheme::default().with_value(QuantValue::Q4F); // Native store -> panics
// after
let scheme = QuantScheme::default()
    .with_value(QuantValue::Q4F)
    .with_store(QuantStore::PackedU32(QuantAccurate::No));

const SUB_BYTE: &[QuantValue] = &[QuantValue::Q4F, QuantValue::Q4S, QuantValue::Q2F, QuantValue::Q2S, QuantValue::E2M1];
assert!(!(scheme.store == QuantStore::Native && SUB_BYTE.contains(&scheme.value)),
    "sub-byte values need a packed store");

When it happens

Trigger: Calling new_qtensor/empty_qtensor with a QuantScheme whose store is QuantStore::Native while scheme.value is Q4F, Q4S, Q2F, Q2S, or E2M1.

Common situations: Configuring quantization from a preset that selects sub-byte values but forgetting to enable packing, or migrating configs where the store field was reset to Native.

Related errors

• {other:?} doesn't support native packing
• Can't store in u32
• Quantization scheme is not valid for dtype {other:?}
• Can't store native sub-byte values
• {other:?} doesn't support native packing

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