cal/claude-home
1
0
Fork 0
Code Issues 6 Pull Requests 4 Actions Packages Projects Releases Wiki Activity
5d1b640b0b
claude-home/gaming/troubleshooting.md
Cal Corum f2258dfade
All checks were successful
Reindex Knowledge Base / reindex (push) Successful in 5s
Details
docs: add Xbox Pi-hole incident report for MLB The Show menu delays 
Pi-hole was gravity-blocking Microsoft telemetry domains that Xbox
calls synchronously during menu transitions, causing 5-10s hangs.
Created per-client Xbox group with allowlist on both Pi-holes.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-14 17:41:36 -05:00

6.8 KiB
Raw Blame History

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.

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