{"record":{"id":"5c57577d875c6b63","repo":"tracel-ai/burn","slug":"matmul-matrix-size-overflow-a-b","errorCode":null,"errorMessage":"matmul: matrix size overflow: {a} * {b}","messagePattern":"matmul: matrix size overflow: (.+?) \\* (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/burn-flex/src/ops/matmul.rs","lineNumber":53,"sourceCode":"    fn one() -> Self {\n        1.0\n    }\n}\n\nimpl GemmScalar for f16 {\n    fn zero() -> Self {\n        f16::from_f32(0.0)\n    }\n    fn one() -> Self {\n        f16::from_f32(1.0)\n    }\n}\n\n/// Checked multiplication for matrix sizes, panics on overflow.\n#[inline]\nfn checked_size(a: usize, b: usize) -> usize {\n    a.checked_mul(b)\n        .unwrap_or_else(|| panic!(\"matmul: matrix size overflow: {a} * {b}\"))\n}\n\n/// Threshold for enabling parallelism (M*N*K operations).\n/// 192^3 = ~7M ops - balance between 128x128 (no parallel) and 256x256 (parallel)\nconst PARALLEL_THRESHOLD: usize = 192 * 192 * 192;\n\n/// Threshold for batch-level parallelism (total ops across all batches).\n/// Use batch parallelism when individual matrices are small but total work is large.\n#[cfg(feature = \"rayon\")]\nconst BATCH_PARALLEL_THRESHOLD: usize = 128 * 128 * 128; // ~2M ops total\n\n/// Get parallelism setting based on matrix size.\nfn get_parallelism(m: usize, n: usize, k: usize) -> gemm::Parallelism {\n    let ops = m.saturating_mul(n).saturating_mul(k);\n    if ops >= PARALLEL_THRESHOLD {\n        #[cfg(feature = \"rayon\")]\n        {\n            gemm::Parallelism::Rayon(0) // 0 = use all available threads","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/tracel-ai/burn/blob/d16f7ba2ed0d41408189384044cc886fb4c8f957/crates/burn-flex/src/ops/matmul.rs#L35-L71","documentation":"checked_size multiplies two matrix dimension sizes (e.g. M*N, K or batch dims) to size the GEMM output buffer. It uses checked_mul and panics when the product overflows usize, i.e. the requested matmul output is too large to address on this platform (practically only on 32-bit targets or with astronomically large dimensions). Called from matmul_batched_gemm, matmul_batched_i32 and matmul_batched_i64.","triggerScenarios":"Calling matmul (Tensor::matmul) with shapes whose flattened output element count exceeds usize::MAX — e.g. huge batch dimensions times M*N on a 32-bit platform, or pathological shapes like [usize-large, k] @ [k, usize-large].","commonSituations":"32-bit embedded/WASM targets with moderately large tensors; a broadcasting bug upstream inflating batch dimensions exponentially; accidental use of byte counts instead of element counts when reshaping.","solutions":["Reduce tensor/batch dimensions; the requested output simply cannot fit in memory anyway.","Chunk the matmul into smaller batch slices and process sequentially.","On 32-bit/WASM targets, switch to 64-bit addressing or keep tensors under the 4GB element-count bound.","Fix upstream broadcasting/expand logic that multiplied batch dims unexpectedly."],"exampleFix":"// before: one giant batched matmul\nlet out = a.matmul(b); // a shape [1_000_000_000, 4096, 4096]\n// after\nfor chunk in a_chunks.iter() {\n    let out_part = chunk.matmul(b); // bounded chunk sizes\n}","handlingStrategy":"validation","validationCode":"let (m, n) = (a.shape()[a.rank() - 2], b.shape()[b.rank() - 1]);\nassert!(m.checked_mul(n).is_some(), \"matmul output size {}*{} overflows usize\", m, n);","typeGuard":null,"tryCatchPattern":"// panic-based; cannot be caught in-process. Validate before calling:\nfn fits_usize(dims: &[usize]) -> bool { dims.iter().try_fold(1usize, |acc, &d| acc.checked_mul(d)).is_some() }","preventionTips":["Keep batch dimensions bounded; chunk giant batched matmuls","Be careful on 32-bit/WASM targets where usize is 4 bytes","Sanity-check shapes (log them) before large matmuls","Fix upstream broadcasting that inflates batch dims"],"tags":["rust","burn","matmul","overflow","usize"],"backgroundTag":"integer-overflow","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"}