claude-home/gaming/troubleshooting.md

title	description	type	domain	tags
Gaming Troubleshooting Guide	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.	troubleshooting	gaming	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:

# Add to environment variables
PROTON_SET_GAME_DRIVE="1"

EasyAntiCheat Issues

Symptoms: Game won't start or kicks you from servers Solution:

# 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:

   # Try forcing NVIDIA GPU
   __NV_PRIME_RENDER_OFFLOAD=1
   __GLX_VENDOR_LIBRARY_NAME=nvidia
   

2. GameScope Issue:

   # Disable GameScope temporarily
   USEGAMESCOPE="0"
   

Performance Stuttering

Symptoms: Frequent frame drops or stuttering Solutions:

1. Enable DXVK Async:

   DXVK_ASYNC="1"
   

2. Force Large Address Aware:

   PROTON_FORCE_LARGE_ADDRESS_AWARE="1"
   

3. Limit Frame Rate:

   # 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:

   nvidia-smi
   lspci | grep -i nvidia
   

2. Verify Vulkan Support:

   vulkaninfo | grep deviceName
   

3. Force NVIDIA in STL:

   USEPRIMERUN="1"  # If on hybrid graphics
   

DLSS Issues

Enable DLSS Support:

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):

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

# 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

# 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 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.

Gray Zone Warfare — EAC Failures on Proton (2026-03-31) [RESOLVED]

Severity: High — game unplayable online Status: RESOLVED — corrupted prebuild world cache file

Problem: EAC errors when connecting to servers on Linux/Proton. Three error codes observed across attempts:

• 0x0002000A — "The client failed an anti-cheat client runtime check" (the actual root cause)
• 0x0002000F — "The client failed to register in time" (downstream timeout)
• 0x00020011 — "The client failed to start the session" (downstream session failure)

Game launches fine, EAC bootstrapper reports success, but fails when joining a server at "Synchronizing Live Data".

Root Cause: A corrupted/stale prebuild world cache file that EAC flagged during runtime checks:

LogEOSAntiCheat: [AntiCheatClient] [PollStatusInternal] Client Violation with Type: 5
Message: Unknown file version (GZW/Content/SKALLA/PrebuildWorldData/World/cache/0xb9af63cee2e43b6c_0x3cb3b3354fb31606.dat)

EAC scanned this file, found an unrecognized version, and flagged a client violation. The other errors (0x0002000F, 0x00020011) were downstream consequences — EAC couldn't complete session registration after the violation.

Compounding factors that made diagnosis harder:

• Epic EOS scheduled maintenance (Fortnite v40.10, Apr 1 08:00-09:30 UTC) returned 503s from api.epicgames.dev/auth/v1/oauth/token, masking the real issue
• steam_api64.dll EOS SDK errors at startup are benign noise under Proton — red herring
• Nuking the compatdata prefix and upgrading Proton happened concurrently, adding confusion

Fix:

1. Delete the specific cache file: rm "GZW/Content/SKALLA/PrebuildWorldData/World/cache/0xb9af63cee2e43b6c_0x3cb3b3354fb31606.dat"
2. Verify game files in Steam — Steam redownloads a fresh copy with different hash
3. Launch game — clean logs, no EAC errors

Key detail: the file was the same size (60.7MB) before and after, but different md5 hash — Steam's verify replaced it with a corrected version.

Log locations:

• EAC bootstrapper: compatdata/2479810/pfx/drive_c/users/steamuser/AppData/Roaming/EasyAntiCheat/.../anticheatlauncher.log
• Game log: compatdata/2479810/pfx/drive_c/users/steamuser/AppData/Local/GZW/Saved/Logs/GZW.log
• STL launch log: ~/.config/steamtinkerlaunch/logs/gamelaunch/id/2479810.log

What did NOT fix it (for reference):

1. Installing Proton EasyAntiCheat Runtime (AppID 1826330) — good to have but not the issue
2. Deleting the entire cache directory without re-verifying — Steam verify re-downloaded the same bad file the first time (20 files fixed); needed a second targeted delete + verify
3. Nuking compatdata prefix for clean rebuild
4. Switching Proton versions (GE-Proton9-25 ↔ GE-Proton10-25)

Lessons:

• When EAC logs show "Unknown file version" for a specific .dat file, delete that file and verify — don't nuke the whole cache or prefix
• steam_api64.dll EOS errors are benign under Proton and not related to EAC failures
• Check Epic's status page for scheduled maintenance before deep-diving Proton issues
• Multiple verify-and-fix cycles may be needed — the first verify can redownload a stale cached version from Steam's CDN

Game version: 0.4.0.0-231948-H (EA Pre-Alpha) Working Proton: GE-Proton10-25 STL config: ~/.config/steamtinkerlaunch/gamecfgs/id/2479810.conf

Useful Commands

Check Running Game Process

# See game processes and GPU usage
nvidia-smi
ps aux | grep -i "ready\|proton"

Monitor Performance

# Real-time GPU monitoring
watch -n 1 nvidia-smi

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

GameScope Debug

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