{"record":{"id":"296ce5fddba3f12d","repo":"tracel-ai/burn","slug":"can-t-store-native-sub-byte-values-296ce5","errorCode":null,"errorMessage":"Can't store native sub-byte values","messagePattern":"Can't store native sub-byte values","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/burn-cubecl/src/tensor/quantization.rs","lineNumber":67,"sourceCode":"                    meta: self.meta.clone(),\n                    device: self.device.clone(),\n                    dtype: DType::I8,\n                    qparams: None,\n                },\n                QuantValue::E4M3 | QuantValue::E5M2 => CubeTensor {\n                    client: self.client.clone(),\n                    handle: self.handle.clone(),\n                    meta: self.meta.clone(),\n                    device: self.device.clone(),\n                    dtype: DType::U8,\n                    qparams: None,\n                },\n                QuantValue::Q4F\n                | QuantValue::Q4S\n                | QuantValue::Q2F\n                | QuantValue::Q2S\n                | QuantValue::E2M1 => {\n                    panic!(\"Can't store native sub-byte values\")\n                }\n            },\n            QuantStore::PackedU32(packed_dim) => {\n                let packed_dim = self.rank() - packed_dim - 1;\n                let mut shape = self.shape();\n                shape[packed_dim] = shape[packed_dim].div_ceil(scheme.num_quants());\n\n                CubeTensor {\n                    client: self.client.clone(),\n                    handle: self.handle.clone(),\n                    meta: Box::new(Metadata::new(shape, self.meta.strides.clone())),\n                    device: self.device.clone(),\n                    dtype: DType::U32,\n                    qparams: None,\n                }\n            }\n            QuantStore::PackedNative(packed_dim) => match scheme.value {\n                QuantValue::E2M1 => {","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/tracel-ai/burn/blob/d16f7ba2ed0d41408189384044cc886fb4c8f957/crates/burn-cubecl/src/tensor/quantization.rs#L49-L85","documentation":"When a quantization scheme uses `QuantStore::Native` (one value per storage element), burn-cubecl cannot natively store sub-byte quantization formats (Q4F, Q4S, Q2F, Q2S, E2M1) because Rust/hardware buffer element types are at least one byte. `quantized_handles` panics to tell you such schemes must use `QuantStore::PackedU32` instead.","triggerScenarios":"Calling `tensor.quantize(&scheme)` / `into_contiguous_quantized`, `launch_matmul` with quantized inputs, `dequantize`, or `q_reshape` where the scheme is `QuantScheme` with `store = QuantStore::Native` and `value = QuantValue::Q4F | Q4S | Q2F | Q2S | E2M1`.","commonSituations":"Constructing a `QuantScheme` manually (e.g. `QuantScheme::default().with_value(QuantValue::Q4F)`) without also setting `.with_store(QuantStore::PackedU32(...))`; copying a scheme used for a native byte-size type (Q8) and swapping only the value to a 4-bit/2-bit format; upgrading library versions where defaults changed.","solutions":["Configure the scheme with `QuantStore::PackedU32(position)` so sub-byte values are packed 4- or 8-per u32: e.g. `QuantScheme::default().with_value(QuantValue::Q4F).with_store(QuantStore::PackedU32(PackedParam::Lhs))`.","Use a scheme constructor that sets a compatible store for the chosen value instead of mixing a Q8-native scheme with a sub-byte value.","If native storage is required, switch to a byte-aligned value such as `QuantValue::Q8F` / `Q8S`."],"exampleFix":"// before\nlet scheme = QuantScheme::default()\n    .with_value(QuantValue::Q4F)\n    .with_store(QuantStore::Native); // panic\n\n// after\nlet scheme = QuantScheme::default()\n    .with_value(QuantValue::Q4F)\n    .with_store(QuantStore::PackedU32(PackedParam::Lhs)); // sub-byte values packed","handlingStrategy":"validation","validationCode":"// validate scheme before quantizing\nlet sub_byte = matches!(scheme.value, QuantValue::Q4F | QuantValue::Q4S | QuantValue::Q2F | QuantValue::Q2S | QuantValue::E2M1);\nassert!(!sub_byte || matches!(scheme.store, QuantStore::PackedU32(_)), \"sub-byte QuantValue requires QuantStore::PackedU32\");","typeGuard":null,"tryCatchPattern":"// panic-based; fix the scheme construction rather than catching\nlet scheme = scheme.with_store(QuantStore::PackedU32(PackedParam::Lhs));","preventionTips":["Never build a QuantScheme by only swapping QuantValue on an existing scheme; set store mode together","Use library-provided scheme constructors/constants for standard formats (e.g. Q4F, Q8S)","Remember rule: native store only for byte-aligned values; sub-byte values must be packed in u32","Add a unit test quantizing/dequantizing a tiny tensor with your exact scheme before training"],"tags":["quantization","burn","rust","gpu"],"backgroundTag":"sub-byte-quantization-storage","analyzedSha":"d16f7ba2ed0d41408189384044cc886fb4c8f957","analyzedAt":"2026-09-05T13:19:14.260Z","contentChangedAt":"2026-09-05T13:19:14.260Z","schemaVersion":2},"datasetVersion":"2026-09-12T17:17:11.597Z"}