# Troubleshooting
**Fix common issues fast.**
## Build Issues
### "Could not find Vulkan SDK"
**Cause:** Vulkan SDK not installed or not in PATH
**Fix:**
1. Install [Vulkan SDK](https://vulkan.lunarg.com/)
2. Restart terminal
3. Verify: `vulkaninfo`
---
### "error: package requires rustc 1.82 or newer"
**Cause:** Rust version too old
**Fix:**
```bash
rustup update stable
cargo clean
cargo build
```
---
### "linker errors about Vulkan"
**Cause:** Vulkan loader not found
**Fix Windows:**
- Install Vulkan SDK
- Add to PATH: `C:\VulkanSDK\<version>\Bin`
**Fix Linux:**
```bash
sudo apt install libvulkan-dev # Ubuntu/Debian
sudo dnf install vulkan-loader-devel # Fedora
```
---
## Runtime Issues
### "Failed to create instance: ERROR_INCOMPATIBLE_DRIVER"
**Cause:** No Vulkan driver or outdated GPU drivers
**Fix:**
1. Update graphics drivers
2. Verify: `vulkaninfo | head -20`
3. Check GPU supports Vulkan 1.3
---
### "Failed to find suitable GPU"
**Cause:** No GPU with required features
**Fix:**
1. Check GPU: `vulkaninfo | grep deviceName`
2. Verify Vulkan 1.3 support
3. Update drivers
---
### "Validation layer errors"
**Cause:** Incorrect Vulkan usage (good catch!)
**Fix:**
1. Read the validation error message
2. Check object lifetimes
3. Verify correct drop order (CORE tier)
4. Common: using destroyed resources
**Disable validation (not recommended):**
```rust
let config = RuntimeConfig {
enable_validation: false,
..Default::default()
};
```
---
### "Out of memory" errors
**Cause:** Too many allocations or large buffers
**Fix:**
1. Reduce buffer sizes
2. Reuse buffers instead of creating new ones
3. Call `device.wait_idle()` before cleanup
4. Check for memory leaks
---
### "Failed to compile shader"
**Cause:** GLSL syntax error or unsupported feature
**Fix:**
1. Check shader error message
2. Verify GLSL version: `#version 450`
3. Test shader with glslangValidator:
```bash
glslangValidator -V shader.glsl
```
4. Check for unsupported extensions
---
## Performance Issues
### Low frame rate
**Diagnose:**
1. Enable validation layers (auto in debug)
2. Check for sync warnings
3. Profile with tools like RenderDoc
**Common causes:**
- Too many pipeline barriers
- Synchronous buffer uploads
- Inefficient descriptor updates
- Shader complexity
**Fixes:**
- Use staging buffers for uploads
- Batch descriptor updates
- Reduce draw calls
- Optimize shaders
---
### Stuttering
**Cause:** CPU stalls or memory pressure
**Fix:**
1. Use multiple frames in flight:
```rust
RuntimeConfig {
in_flight_frames: 3, ..Default::default()
}
```
2. Async buffer uploads
3. Reuse command buffers
---
## Tier-Specific Issues
### EZ Tier
**"Cannot customize X"**
→ Drop to EX or CORE tier for more control
**"Need more complex pipeline"**
→ Use EX tier's PipelineBuilder
---
### EX Tier
**"Invalid ShaderId/PipelineId"**
→ Check ID came from same ShaderManager
**"Resource lifetime issues"**
→ Manager owns resources, don't manually destroy
---
### CORE Tier
**"Use after free" / "Segfault"**
→ Check drop order. Device must outlive all resources.
**"VK_ERROR_DEVICE_LOST"**
→ Validation layers will show the cause. Usually: invalid sync or resource usage.
---
## Platform-Specific
### Windows
**"DLL not found"**
→ Install Vulkan runtime from GPU driver or SDK
**"Access denied" errors**
→ Run as administrator or check antivirus
---
### Linux
**"Could not open display"**
→ Surface creation needs a window (not provided by shdrlib)
**"libvulkan.so.1 not found"**
```bash
sudo apt install vulkan-loader
```
---
### macOS
**"Vulkan not supported"**
→ Install MoltenVK (included in Vulkan SDK)
**"Metal errors"**
→ MoltenVK translates Vulkan to Metal. Some features unsupported.
---
## Debugging Tips
### Enable Verbose Logging
```rust
// Set env var before running
// Windows:
set RUST_LOG=shdrlib=debug
cargo run
// Linux/macOS:
RUST_LOG=shdrlib=debug cargo run
```
### Use Validation Layers
Auto-enabled in debug builds. Check stderr for errors.
### Use RenderDoc
1. Install [RenderDoc](https://renderdoc.org/)
2. Capture frame
3. Inspect API calls and resources
### Check Vulkan
```bash
# List devices
vulkaninfo
# Check validation layers
# Test Vulkan
vkcube # Should show a spinning cube
```
---
## Still Stuck?
1. Check [FAQ](faq.md)
2. Search [GitHub Issues](https://github.com/paulburnettjones-wq/shdrlib/issues)
3. Ask in [Discussions](https://github.com/paulburnettjones-wq/shdrlib/discussions)
4. File a [Bug Report](https://github.com/paulburnettjones-wq/shdrlib/issues/new)
**Include in bug reports:**
- OS and version
- GPU model
- Vulkan version (`vulkaninfo | head -20`)
- Rust version (`rustc --version`)
- Full error message
- Minimal reproducible example