# Troubleshooting

## 1. `cargo build` fails with "no matching package"

**Symptom:** Build fails with `could not find package` for wgpu or winit.

**Cause:** Version typo in `Cargo.toml`. wgpu and winit have specific major versions.

**Fix:** Verify your dependency versions:
```toml
wgpu = "29"
winit = "0.30"
tokio = { version = "1", features = ["rt", "macros"] }
bytemuck = { version = "1", features = ["derive"] }
log = "0.4"
simple_logger = "5"
```

## 2. Window opens but shows black screen

**Symptom:** Window appears but is entirely black. No triangle visible.

**Cause:** One (or more) of several common rendering misconfigurations:
- Pipeline not set: `pass.set_pipeline()` not called
- Vertex buffer not bound: `pass.set_vertex_buffer()` not called
- Draw call wrong: `draw()` arguments incorrect (must be `draw(0..3, 0..1)` — two ranges)
- Triangle wound clockwise: `FrontFace::Ccw` requires counter-clockwise vertex order
- Format mismatch: `ColorTargetState::format` must match `SurfaceConfiguration::format`
- Present omitted: `surface_texture.present()` must be called to show rendered frame

**Fix:** Check each item above. Verify the pipeline is set, buffer is bound, draw uses two `Range<u32>` arguments, vertices are CCW, formats match, and `present()` is called.

## 3. Washed-out or wrong colors

**Symptom:** Triangle renders but colors look dull or incorrect.

**Cause:** `SurfaceConfiguration::view_formats` missing `add_srgb_suffix()`. Without sRGB gamma correction, colors appear washed out.

**Fix:** Ensure `view_formats` includes the sRGB variant:
```rust
view_formats: vec![format.add_srgb_suffix()],
```

## 4. Panic: "No adapter found"

**Symptom:** Program crashes immediately with `No GPU adapter found`.

**Cause:** No Vulkan driver installed. wgpu on Linux requires Vulkan.

**Fix:**
```bash
sudo apt install libvulkan1 mesa-vulkan-drivers
vulkaninfo  # verify installation
```

## 5. Panic: "Surface lost"

**Symptom:** Program crashes with a surface lost error during rendering.

**Cause:** Display server restarted or GPU context was reset. The [Surface](concepts/GLOSSARY.md#surface) is permanently invalidated.

**Fix:** In the tutorial, this means the window needs to be reopened. In production code, handle the `Lost` variant of `CurrentSurfaceTexture` by recreating the surface via `Instance::create_surface()`.

## 6. Wayland surface crashes or doesn't render

**Symptom:** Program crashes or shows blank window on Wayland.

**Cause:** winit's Wayland backend may have compatibility issues with certain compositors.

**Fix:** Force X11 backend:
```bash
WINIT_UNIX_BACKEND=x11 cargo run
```

## 7. Window won't close

**Symptom:** Clicking the X button or pressing Escape doesn't close the window.

**Cause:** `ApplicationHandler::exiting()` not implemented, or `event_loop_ctl.exit()` not called.

**Fix:** Ensure `exiting()` (note: NOT `closing()`) is implemented:
```rust
fn exiting(&mut self, event_loop_ctl: &ActiveEventLoop) {
    event_loop_ctl.exit();
}
```

## 8. CPU at 100%

**Symptom:** One CPU core at 100% usage.

**Cause:** `ControlFlow::Poll` drives `RedrawRequested` events continuously. Every frame renders and queues another redraw. This is the expected behavior for a `ControlFlow::Poll` render loop.

**Fix:** No fix needed — this is expected for a continuous redraw demo. For production, switch to `ControlFlow::Wait` and call `request_redraw()` only when state changes.

## 9. Shader compilation or pipeline creation error

**Symptom:** Program panics during `create_render_pipeline` with a shader validation error.

**Cause:** `@location` numbers in WGSL don't match `shader_location` numbers in Rust's `VertexAttribute`, or `@builtin(position)` is missing from vertex shader output.

**Fix:** Check the log output for validation messages. Verify:
- WGSL `@location(0)` matches Rust `shader_location: 0`
- WGSL `@location(1)` matches Rust `shader_location: 1`
- Vertex shader outputs `@builtin(position) clip_position: vec4<f32>`

## 10. Triangle shows one solid color instead of gradient

**Symptom:** Triangle renders but is a single uniform color instead of smoothly blending.

**Cause:** Fragment shader returns a constant color instead of passing through `input.vertex_color`. The [rasterizer](concepts/GLOSSARY.md#rasterizer) interpolates vertex colors automatically, but only if the fragment shader uses them.

**Fix:** Ensure fragment shader returns the interpolated vertex color:
```wgsl
@fragment
fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
    return vec4<f32>(input.vertex_color, 1.0);
}
```

Not this (which returns a solid color):
```wgsl
return vec4<f32>(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<f32>` where `vec4<f32>` 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

## 12. GPU debugging with RenderDoc

**Symptom:** Rendering issues that are difficult to diagnose (artifacts, wrong output, silent failures).

**Cause:** GPU debugging is hard with standard tools. Graphics pipeline state, shader execution, and buffer contents are not easily inspectable at runtime.

**Fix:** Use [RenderDoc](https://renderdoc.org/) — a standalone GPU debugging tool supporting frame capture, pipeline state inspection, and shader debugging. It works with Vulkan (Linux), DX12 (Windows), and OpenGL. Launch RenderDoc, attach to your wgpu process, and capture frames to inspect the full graphics pipeline step by step.

## Additional Resources

- [Glossary](concepts/GLOSSARY.md) — Every term defined
- [Graphics Pipeline](concepts/graphics-pipeline.md) — Pipeline stage overview
- [Coordinate Systems](concepts/coordinate-systems.md) — NDC and transformation spaces
- [Shader Basics](concepts/shader-basics.md) — WGSL and shader concepts
- [wgpu documentation](https://docs.rs/wgpu/29.0.0/) — Official wgpu 29 API docs
- [wgpu repository](https://github.com/gfx-rs/wgpu) — Examples and issue tracker