From 2586e9b813625ce510434e100627625b00c8bd93 Mon Sep 17 00:00:00 2001 From: Krishna Ayyalasomayajula Date: Sat, 30 May 2026 20:49:31 -0500 Subject: [PATCH] docs: add shader compilation troubleshooting entry --- docs/TROUBLESHOOTING.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 3bddece..92ab927 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -123,6 +123,23 @@ Not this (which returns a solid color): return vec4(1.0, 1.0, 1.0, 1.0); // wrong: solid white ``` +## 11. WGSL shader compilation errors + +**Symptom:** Program panics or logs errors during `device.create_shader_module()` or `create_render_pipeline()` with messages referencing WGSL validation failures. + +**Cause:** wgpu validates WGSL shaders at pipeline creation time, not at runtime. Errors surface immediately when the shader module is created or when the render pipeline references it. Common causes include: +- Syntax errors: typos in WGSL (missing semicolons, mismatched braces, incorrect keywords) +- Type mismatches: passing `vec2` where `vec4` is expected, or mixing signed/unsigned types +- Missing `@location` or `@builtin` attributes: vertex/fragment shader I/O without proper decoration +- Entry point not found: the `@vertex` or `@fragment` function name doesn't match the pipeline descriptor's `entry_point` field + +**Fix:** Read wgpu's error messages carefully — they include the shader source line and column where the issue was detected. Follow this checklist: +- Check the reported line/column in your WGSL source for syntax issues +- Verify all type signatures match between vertex shader output and fragment shader input +- Ensure every varying uses `@location(N)` and position output uses `@builtin(position)` +- Confirm the function name in your `@vertex`/`@fragment` declaration matches the string you pass to `ProgrammableStage::entry_point` +- If the error message is unclear, try compiling the shader in isolation to isolate syntax vs. pipeline-binding issues + ## Additional Resources - [Glossary](concepts/GLOSSARY.md) — Every term defined