claude-home/gaming/troubleshooting.md

---
title: "Gaming Troubleshooting Guide"
description: "Troubleshooting solutions for Linux gaming issues including launch failures, performance problems, audio/display issues, NVIDIA GPU detection, DLSS, ray tracing, and Ready or Not-specific fixes."
type: troubleshooting
domain: gaming
tags: [steam, proton, stl, nvidia, dlss, gamescope, ready-or-not, dxvk, audio, pipewire]
---

# Gaming Troubleshooting Guide

## Quick Fixes by Issue Type

### Game Won't Launch
1. **Check Proton Version**: Try GE-Proton10-11 or Proton 8.0-5
2. **Verify Paths**: Ensure CUSTOMCMD points to correct executable
3. **Disable STL**: Test with vanilla Proton first
4. **Check Dependencies**: Ensure required libraries are installed

### Performance Issues
1. **Enable GameMode**: `USEGAMEMODERUN="1"`
2. **Check DXVK Settings**: Ensure ESYNC/FSYNC are enabled
3. **Monitor GPU Usage**: Use MangoHUD to identify bottlenecks
4. **Adjust GameScope**: Try different scaling options

### Audio Problems
1. **Increase Latency**: `STL_PULSE_LATENCY_MSEC="120"`
2. **PipeWire Fix**: `PIPEWIRE_LATENCY="256/48000"`
3. **Disable Audio Acceleration**: In game settings
4. **Check Audio Device**: Ensure correct output selected

### Display Issues
1. **GameScope Resolution**: Match native monitor resolution
2. **Fullscreen Toggle**: Try Alt+Enter in-game
3. **Disable Compositing**: Temporarily for testing
4. **Check Graphics Drivers**: Ensure latest NVIDIA drivers

## Ready or Not Specific Issues

### Menu Freeze / Mods Menu
**Symptoms**: Game freezes when accessing mods or certain menus
**Solution**: 
```bash
# Add to environment variables
PROTON_SET_GAME_DRIVE="1"
```

### EasyAntiCheat Issues
**Symptoms**: Game won't start or kicks you from servers
**Solution**:
```bash
# Add to game arguments
GAMEARGS="-noeac"
```
**Note**: This disables EAC and prevents online play

### Black Screen on Launch
**Symptoms**: Game launches but shows black screen
**Solutions**:
1. **NVIDIA Driver Issue**:
   ```bash
   # Try forcing NVIDIA GPU
   __NV_PRIME_RENDER_OFFLOAD=1
   __GLX_VENDOR_LIBRARY_NAME=nvidia
   ```

2. **GameScope Issue**:
   ```bash
   # Disable GameScope temporarily
   USEGAMESCOPE="0"
   ```

### Performance Stuttering
**Symptoms**: Frequent frame drops or stuttering
**Solutions**:
1. **Enable DXVK Async**:
   ```bash
   DXVK_ASYNC="1"
   ```

2. **Force Large Address Aware**:
   ```bash
   PROTON_FORCE_LARGE_ADDRESS_AWARE="1"
   ```

3. **Limit Frame Rate**:
   ```bash
   # In GameScope args
   GAMESCOPE_ARGS="-W 3440 -H 1440 -r 240 -f --immediate-flips --rt --fps-limit-method=2 --"
   ```

## NVIDIA-Specific Troubleshooting

### GPU Not Detected
1. **Check Driver Installation**:
   ```bash
   nvidia-smi
   lspci | grep -i nvidia
   ```

2. **Verify Vulkan Support**:
   ```bash
   vulkaninfo | grep deviceName
   ```

3. **Force NVIDIA in STL**:
   ```bash
   USEPRIMERUN="1"  # If on hybrid graphics
   ```

### DLSS Issues
**Enable DLSS Support**:
```bash
PROTON_ENABLE_NVAPI="1"
USEDLSS="1"
PROTON_HIDE_NVIDIA_GPU="0"  # Don't hide GPU from game
```

### Ray Tracing Problems
**Enable Ray Tracing** (DX12 games only):
```bash
USERAYTRACING="1"
STL_VKD3D_CONFIG="dxr"
```

## Configuration File Locations

### Steam Tinker Launch
- **Global Config**: `~/.config/steamtinkerlaunch/global.conf`
- **Game Configs**: `~/.config/steamtinkerlaunch/gamecfgs/1144200.conf`
- **Logs**: `~/.config/steamtinkerlaunch/logs/`

### Proton/Steam
- **Compatdata**: `~/.steam/steam/steamapps/compatdata/1144200/`
- **Game Install**: `~/.steam/steam/steamapps/common/Ready Or Not/`

## Emergency Recovery

### Reset Game Configuration
```bash
# Backup current config
cp ~/.config/steamtinkerlaunch/gamecfgs/1144200.conf ~/.config/steamtinkerlaunch/gamecfgs/1144200.conf.backup

# Reset to minimal config
cat > ~/.config/steamtinkerlaunch/gamecfgs/1144200.conf << 'EOF'
USEGAMEMODERUN="1"
USEPROTON="GE-Proton10-11"
GAMEARGS="-noeac"
EOF
```

### Clean Proton Prefix
```bash
# Remove compatdata (Steam will recreate)
rm -rf ~/.steam/steam/steamapps/compatdata/1144200/
# Launch game to regenerate prefix
```

### Verify Game Files
1. Open Steam
2. Right-click Ready or Not
3. Properties → Local Files → Verify integrity

## Testing Methodology

### Systematic Testing
1. **Vanilla Test**: Disable all STL settings
2. **Minimal STL**: Add only essential settings
3. **Incremental**: Add one setting at a time
4. **Document**: Record what works/doesn't work

### Performance Testing
1. **Baseline**: Test without any modifications
2. **With STL**: Test with recommended settings
3. **Compare**: Use MangoHUD to compare frame rates
4. **Optimize**: Adjust settings based on results

## Common Error Messages

| Error | Cause | Solution |
|-------|-------|----------|
| "Failed to initialize graphics" | Driver/GPU issue | Update NVIDIA drivers |
| "EasyAntiCheat timeout" | EAC conflict | Add `-noeac` argument |
| "Access violation" | Memory issue | Enable PROTON_FORCE_LARGE_ADDRESS_AWARE |
| "Vulkan initialization failed" | DXVK issue | Try PROTON_USE_WINED3D="1" |

## Hardware-Specific Notes

### High Refresh Rate Monitors
- Ensure GameScope refresh rate matches monitor
- May need to limit frame rate for stability
- Test with vsync on/off

### Multiple Monitors
- Specify primary display in GameScope
- May need to disable secondary monitors during play
- Check for focus issues

### HDR Displays
For full HDR setup (vk-hdr-layer, KDE config, per-API env vars), see the **steam-game-setup** skill:
`.claude/skills/steam-game-setup/SKILL.md` → HDR Configuration section

## Xbox / Console Issues

### Menu Delays Caused by Pi-hole Blocking
**Symptoms**: Multi-second (5-10s) hangs when toggling menus in online games (e.g., MLB The Show)
**Root Cause**: Pi-hole gravity-blocks Microsoft telemetry domains that the Xbox calls synchronously during menu transitions. The game gets `0.0.0.0` from DNS, attempts TCP connect, and waits for timeout.
**Solution**: Create a per-client Xbox group in Pi-hole with allowlist entries for the blocked domains. See [xbox-pihole-mlb-the-show-incident.md](xbox-pihole-mlb-the-show-incident.md) for full details.
**Key domains to whitelist for Xbox**:
- `settings-win.data.microsoft.com`
- `arc.msn.com`
- `v10.events.data.microsoft.com`
- `v20.events.data.microsoft.com`
- `activity.windows.com`

**Diagnostic tip**: Look for rapid retry patterns in Pi-hole logs (same domain queried every 1-3s from the Xbox IP) — this signals a blocked domain causing timeout loops.

## Useful Commands

### Check Running Game Process
```bash
# See game processes and GPU usage
nvidia-smi
ps aux | grep -i "ready\|proton"
```

### Monitor Performance
```bash
# Real-time GPU monitoring
watch -n 1 nvidia-smi

# STL logs
tail -f ~/.config/steamtinkerlaunch/logs/steamtinkerlaunch.log
```

### GameScope Debug
```bash
# Launch with GameScope debug
gamescope --debug -- steam steam://rungameid/1144200
```