{"record":{"id":"e64e040a127f9b1e","repo":"gfx-rs/wgpu","slug":"byte-slice-does-not-start-with-spir-v-magic-number","errorCode":null,"errorMessage":"byte slice does not start with SPIR-V magic number. Make sure you are using a binary SPIR-V file.","messagePattern":"byte slice does not start with SPIR-V magic number\\. Make sure you are using a binary SPIR-V file\\.","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"wgpu/src/util/spirv.rs","lineNumber":70,"sourceCode":"            } else {\n                None\n            }\n        }\n        _ => None, // fallthrough case = between 1 and 3 bytes\n    };\n\n    match found_magic_number {\n        Some(needs_byte_swap) => {\n            // Note: this assertion is relied upon for the soundness of `make_spirv_const()`.\n            assert!(\n                bytes.len().is_multiple_of(mem::size_of::<u32>()),\n                \"SPIR-V data must be a multiple of 4 bytes long\"\n            );\n\n            needs_byte_swap\n        }\n        None => {\n            panic!(\n                \"byte slice does not start with SPIR-V magic number. \\\n            Make sure you are using a binary SPIR-V file.\"\n            );\n        }\n    }\n}\n\n#[cfg_attr(not(feature = \"spirv\"), expect(rustdoc::broken_intra_doc_links))]\n/// Version of [`make_spirv()`] intended for use with\n/// [`Device::create_shader_module_passthrough()`].\n///\n/// Returns a raw slice instead of [`ShaderSource`].\n///\n/// # Panics\n///\n/// This function panics if:\n///\n/// - `data.len()` is not a multiple of 4","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/gfx-rs/wgpu/blob/3e11ff59bf3f9795d285ecc045014089640d7248/wgpu/src/util/spirv.rs#L52-L88","documentation":"This panic is thrown by wgpu's `util::make_spirv_raw`/`make_spirv_const` helpers when the input byte slice does not begin with the SPIR-V magic number 0x07230203. These helpers only accept binary SPIR-V modules; the magic check is the first sanity gate before any other decoding. Passing WGSL text, GLSL source, or a corrupted/truncated binary will hit this panic.","triggerScenarios":"Calling `util::make_spirv_raw(bytes)` or `util::make_spirv_const(words/bytes)` with a slice whose first 4 bytes are not the little/big-endian SPIR-V magic word 0x07230203 — e.g. passing WGSL/GLSL source text, a JSON/spvasm disassembly, or a wrongly-encoded buffer.","commonSituations":"Loading a shader from disk but pointing at a .wgsl or .spvasm file instead of a compiled .spv; compiling GLSL to SPIR-V with text output enabled; a build script failing silently so a placeholder or empty file is embedded; byte-order/encoding mangling when embedding shaders in firmware or via include_bytes of the wrong artifact.","solutions":["Compile your shader to binary SPIR-V (e.g. glslc shader.comp -o shader.spv or glslangValidator -V) and pass the .spv bytes","If you are passing source code, switch to the correct ingestion API: create the shader module from WGSL via ShaderModuleDescriptor with source=Wgsl, or use naga to transpile","Verify the first 4 bytes of your data are [0x03, 0x02, 0x23, 0x07] (or the reversed word) before calling the helper","Check your build pipeline actually produced and embedded the compiled binary (print bytes.len() and the magic word)"],"exampleFix":"// before\nlet module = device.create_shader_module(wgpu::util::make_spirv_raw(\n    include_bytes!(\"shader.wgsl\"),\n));\n// after\nlet module = device.create_shader_module(wgpu::ShaderModuleDescriptor {\n    label: Some(\"shader\"),\n    source: wgpu::ShaderSource::Wgsl(include_str!(\"shader.wgsl\").into()),\n});","handlingStrategy":"validation","validationCode":"fn is_binary_spirv(bytes: &[u8]) -> bool {\n    bytes.len() >= 4 && bytes[..4] == [0x03, 0x02, 0x23, 0x07]\n}\nif !is_binary_spirv(&shader_bytes) {\n    panic!(\"not a binary SPIR-V file — did you mean to use ShaderSource::Wgsl?\");\n}","typeGuard":"fn is_binary_spirv(bytes: &[u8]) -> bool {\n    bytes.len() >= 4 && u32::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]) == 0x07230203\n}","tryCatchPattern":null,"preventionTips":["Always compile GLSL/HLSL to .spv binaries before ingestion; never point include_bytes! at source files","Add a build.rs check that asserts the embedded shader file starts with the SPIR-V magic","Use ShaderSource::Wgsl for WGSL text instead of the SPIR-V helpers","Log bytes.len() and the first word when a shader fails to load"],"tags":["spirv","wgpu","shader-loading","panic"],"backgroundTag":"invalid-shader-binary","analyzedSha":"3e11ff59bf3f9795d285ecc045014089640d7248","analyzedAt":"2026-09-03T01:43:21.459Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T07:17:11.731Z"}