# Troubleshooting Guide
Solutions to common shdrlib issues.
## Table of Contents
- [Installation Issues](#installation-issues)
- [Runtime Errors](#runtime-errors)
- [Shader Compilation](#shader-compilation)
- [Rendering Issues](#rendering-issues)
- [Performance Problems](#performance-problems)
- [Platform-Specific](#platform-specific)
---
## Installation Issues
### Rust Version Too Old
**Error:**
```
error: package `shdrlib` requires rustc 1.82.0 or newer
```
**Solution:**
```bash
rustup update stable
rustc --version # Verify 1.82+
```
### Vulkan Loader Not Found
**Error:**
```
Error: VulkanLibraryLoadFailure
```
**Solutions:**
**Windows:**
1. Install latest graphics drivers
2. Install [Vulkan SDK](https://vulkan.lunarg.com/)
3. Restart your system
**Linux:**
```bash
# Ubuntu/Debian
sudo apt install libvulkan1 vulkan-tools
# Fedora
sudo dnf install vulkan-loader vulkan-tools
# Arch
sudo pacman -S vulkan-icd-loader vulkan-tools
```
**macOS:**
```bash
brew install --cask vulkan-sdk
# Or download from vulkan.lunarg.com
```
**Verify:**
```bash
### Missing Validation Layers (Debug Only)
**Error:**
```
WARN: Validation layers requested but not available
```
**Solutions:**
This only affects debug builds. Either:
**Option 1: Install validation layers**
```bash
# Linux
sudo apt install vulkan-validationlayers
# macOS
# Included in Vulkan SDK
# Windows
# Included in Vulkan SDK
```
**Option 2: Build in release mode**
```bash
cargo build --release
```
### Compilation Errors
**Error:**
```
error: cannot find crate `ash`
```
**Solution:**
```bash
cargo add ash
```
---
## Runtime Errors
### No Suitable Physical Device
**Error:**
```
Error: NoSuitableDevice
```
**Causes:**
1. No GPU with Vulkan 1.3 support
2. Outdated graphics drivers
3. Running in VM without GPU pass-through
**Solutions:**
**Check Vulkan support:**
```bash
```
**Update drivers:**
- **NVIDIA:** Download from nvidia.com
- **AMD:** Download from amd.com
- **Intel:** Download from intel.com
**Check available devices:**
```bash
vulkaninfo --summary
```
### Out of Memory
**Error:**
```
Error: VulkanError(ERROR_OUT_OF_DEVICE_MEMORY)
```
**Causes:**
- Creating too many large textures
- Memory leak (not destroying resources)
- GPU VRAM exhausted
**Solutions:**
**1. Destroy unused resources:**
```rust
// Resources are automatically dropped when they go out of scope
{
let texture = renderer.create_texture(...)?;
// Use texture
} // Automatically destroyed here
```
**2. Check resource sizes:**
```rust
// Instead of:
let huge_texture = renderer.create_texture(8192, 8192, ...)?; // 256MB!
// Try:
let texture = renderer.create_texture(2048, 2048, ...)?; // 16MB
```
**3. Profile memory usage:**
```bash
# Use GPU monitoring tools
nvidia-smi # NVIDIA
radeontop # AMD
intel_gpu_top # Intel
```
### Device Lost
**Error:**
```
Error: VulkanError(ERROR_DEVICE_LOST)
```
**Causes:**
- GPU driver crash
- Infinite loop in shader
- Invalid GPU commands
- Hardware issue
**Solutions:**
**1. Check validation errors:**
```bash
# Run in debug mode
cargo run
# Check for validation warnings before the crash
```
**2. Simplify shaders:**
```glsl
// Remove complex logic
// Add early returns
// Check for infinite loops
```
**3. Update drivers:**
- Latest GPU drivers often fix crashes
**4. Check hardware:**
```bash
# Run GPU stress test
vkcube # Should run without crashes
```
---
## Shader Compilation
### GLSL Syntax Errors
**Error:**
```
Error: ShaderCompilationFailed("unexpected token")
```
**Solutions:**
**1. Check GLSL version:**
```glsl
#version 450 // Required for Vulkan
```
**2. Common mistakes:**
```glsl
// ❌ Wrong
uniform mat4 transform; // Missing layout
// ✅ Correct
layout(set = 0, binding = 0) uniform Transform {
mat4 matrix;
} transform;
```
**3. Check extension support:**
```glsl
// Some extensions not supported by naga
#extension GL_ARB_xxx : enable // May not work
// Use Vulkan-compatible GLSL instead
```
### Unsupported GLSL Features
**Error:**
```
Error: UnsupportedShaderFeature
```
**Cause:** naga doesn't support all GLSL extensions
**Solutions:**
**1. Use GLSL 450 core profile:**
```glsl
#version 450 core
// Avoid extensions
```
**2. Check naga compatibility:**
- Most GLSL 4.50 features supported
- Some extensions not available
- Ray tracing: limited support
**3. Use SPIR-V directly:**
```rust
// Pre-compile with glslc
// glslc shader.glsl -o shader.spv
// Load SPIR-V
let spirv = std::fs::read("shader.spv")?;
let shader = Shader::from_spirv(&device, &spirv, stage)?;
```
### Reflection Errors
**Error:**
```
Error: ReflectionFailed
```
**Cause:** Can't extract bindings/push constants from SPIR-V
**Solutions:**
**1. Use explicit layouts:**
```glsl
// ✅ Explicit
layout(set = 0, binding = 0) uniform sampler2D tex;
layout(set = 0, binding = 1) uniform UBO { mat4 proj; } ubo;
// ❌ Implicit layouts may fail reflection
uniform sampler2D tex;
```
**2. Disable reflection (advanced):**
```rust
// Use manual descriptor layouts
// Don't rely on shader reflection
```
---
## Rendering Issues
### Black Screen / Nothing Rendering
**Checklist:**
**1. Check validation errors:**
```bash
cargo run # Debug mode enables validation
```
**2. Verify shaders:**
```glsl
// Add debug output
layout(location = 0) out vec4 outColor;
void main() {
outColor = vec4(1.0, 0.0, 0.0, 1.0); // Bright red
}
```
**3. Check viewport/scissor:**
```rust
frame.set_viewport(0.0, 0.0, width as f32, height as f32);
frame.set_scissor(0, 0, width, height);
```
**4. Verify pipeline:**
```rust
// Make sure pipeline is bound
frame.bind_pipeline(pipeline)?;
```
**5. Check draw calls:**
```rust
frame.draw(vertex_count, 1, 0, 0); // At least 3 vertices for triangle
```
### Flickering / Stuttering
**Causes:**
- Synchronization issues
- Frame pacing problems
- GPU starvation
**Solutions:**
**1. Check frame synchronization:**
```rust
// Use proper frame pacing
runtime.begin_frame()?;
// ... render ...
runtime.end_frame(&Default::default())?;
```
**2. Enable VSync** (if using swapchain)
**3. Profile frame time:**
```rust
let start = std::time::Instant::now();
// ... render ...
println!("Frame time: {:?}", start.elapsed());
```
### Wrong Colors / Corruption
**Causes:**
- Wrong image format
- Incorrect data layout
- Missing color attachment
**Solutions:**
**1. Check format:**
```rust
// Make sure formats match
let texture = renderer.create_texture(
256, 256,
Format::R8G8B8A8_UNORM // Common format
)?;
```
**2. Verify data layout:**
```rust
#[repr(C)] // Required for GPU data
struct Vertex {
pos: [f32; 2],
color: [f32; 3],
}
```
**3. Check color attachment:**
```rust
PipelineBuilder::new()
.color_attachment_formats(vec![Format::R8G8B8A8_UNORM])
// Must match render target format
```
---
## Performance Problems
### Low FPS / Slow Rendering
**Profile first:**
**1. Check GPU vs CPU bottleneck:**
```rust
// Measure GPU time
let query_pool = /* create timestamp queries */;
// Measure CPU time
let start = Instant::now();
// ... render ...
println!("CPU time: {:?}", start.elapsed());
```
**2. Common CPU issues:**
- Too many draw calls → batch geometry
- Recreating resources → cache pipelines/buffers
- Synchronization stalls → overlap work
**3. Common GPU issues:**
- Overdraw → optimize triangle order
- Shader complexity → profile with RenderDoc
- Memory bandwidth → compress textures
### High Memory Usage
**1. Check texture sizes:**
```rust
// 4K texture = 64MB uncompressed
// Use compressed formats or smaller sizes
```
**2. Destroy unused resources:**
```rust
// Resources auto-drop, but you can be explicit
drop(old_texture);
```
**3. Profile allocations:**
```bash
# Use memory profiler
cargo build --release
valgrind --tool=massif ./target/release/my_app
```
### Compilation is Slow
**1. Use incremental compilation** (default)
**2. Reduce dependencies:**
```toml
# Only include what you need
[dependencies]
shdrlib = { version = "0.1", default-features = false }
```
**3. Use `cargo check`** for fast iteration:
```bash
cargo check # Fast syntax checking
cargo build # Full build when ready
```
---
## Platform-Specific
### Windows
**Issue: "vulkan-1.dll not found"**
**Solution:**
- Update graphics drivers
- Install Vulkan SDK
- Check `C:\Windows\System32\vulkan-1.dll` exists
**Issue: Multiple GPUs**
**Solution:**
```rust
// Select specific GPU via physical device
// shdrlib defaults to first discrete GPU
```
### Linux
**Issue: Permission denied for GPU**
**Solution:**
```bash
# Add user to video/render group
sudo usermod -a -G video,render $USER
# Log out and back in
```
**Issue: Wayland vs X11**
**Solution:**
```bash
# Force X11 if Wayland has issues
GDK_BACKEND=x11 cargo run
```
**Issue: Mesa driver too old**
**Solution:**
```bash
# Update Mesa
sudo apt update && sudo apt upgrade mesa-*
# Or use PPA for latest
sudo add-apt-repository ppa:kisak/kisak-mesa
sudo apt update && sudo apt upgrade
```
### macOS
**Issue: MoltenVK not found**
**Solution:**
```bash
brew install --cask vulkan-sdk
# Or download from vulkan.lunarg.com
```
**Issue: Validation layers verbose/broken**
**Solution:**
```bash
# Disable validation on macOS if issues
cargo build --release # No validation in release
```
**Issue: Metal-specific limitations**
**Solution:**
- Some Vulkan features unavailable
- Check MoltenVK compatibility: https://github.com/KhronosGroup/MoltenVK
---
## Debugging Tips
### Enable Verbose Logging
```rust
// Set environment variable
std::env::set_var("RUST_LOG", "shdrlib=trace");
```
Or:
```bash
RUST_LOG=shdrlib=trace cargo run
```
### Use RenderDoc
1. Download RenderDoc: https://renderdoc.org/
2. Launch your app through RenderDoc
3. Capture frame (F12)
4. Inspect:
- Draw calls
- Pipeline state
- Shaders
- Textures
### Validation Layers
Debug builds automatically enable validation. Read messages carefully!
```
VUID-vkCmdDraw-None-02859: Shader requires VkPhysicalDeviceFeatures::geometryShader
```
This tells you:
- What's wrong (geometry shader not enabled)
- Where to look (VkPhysicalDeviceFeatures)
- How to fix (enable feature)
### Minimal Reproduction
Narrow down issues:
```rust
// Start with simplest case
let renderer = EzRenderer::new()?;
println!("✅ Setup works");
let pipeline = renderer.quick_pipeline(VERT, FRAG)?;
println!("✅ Pipeline works");
renderer.render_frame(|frame| {
frame.bind_pipeline(pipeline)?;
frame.draw(3, 1, 0, 0);
Ok(())
})?;
println!("✅ Rendering works");
```
Find which line fails, then focus on that.
---
## Getting Help
### Before asking:
1. ✅ Check this troubleshooting guide
2. ✅ Read [FAQ](faq.md)
3. ✅ Search [GitHub Issues](https://github.com/paulburnettjones-wq/shdrlib/issues)
4. ✅ Try minimal reproduction
### When asking:
Include:
- **OS and version** (Windows 11, Ubuntu 22.04, etc.)
- **Rust version** (`rustc --version`)
- **GPU and driver** (`vulkaninfo | head`)
- **shdrlib version** (Cargo.toml)
- **Minimal code** to reproduce
- **Full error message** with backtrace
**Good issue report:**
```markdown
**OS:** Windows 11
**Rust:** 1.82.0
**GPU:** NVIDIA RTX 3060, Driver 536.23
**shdrlib:** 0.1.0
**Problem:** Black screen when rendering triangle
**Code:**
```rust
[minimal reproduction]
```
**Error:**
```
[full error message]
```
```
**Bad issue report:**
```
it doesnt work help
```
### Where to ask:
- 🐛 **Bugs:** [GitHub Issues](https://github.com/paulburnettjones-wq/shdrlib/issues)
- 💬 **Questions:** [GitHub Discussions](https://github.com/paulburnettjones-wq/shdrlib/discussions)
- 📖 **Docs unclear:** Open docs issue or PR
---
**Still stuck?** Open a [GitHub Discussion](https://github.com/paulburnettjones-wq/shdrlib/discussions) with details!
---
**Last Updated:** October 30, 2025