# Steam Deck Black Screen Bug Report - X11/GLX Rendering Failure in steamwebhelper

this summary generated with the help of AI, but debugging was done by me at the terminal.

## Summary
After normal use, Steam Deck gaming mode displays correctly for ~5 seconds after boot, then screen goes completely black. System remains responsive (can SSH in), but display is unusable. Issue persists across multiple reboots.

## System Information
- **Device**: Steam Deck
- **OS**: SteamOS 3.x (steamdeck-beta variant)
- **Date**: October 4, 2025
- **Affected Component**: steamwebhelper (Steam UI renderer)

## Steps i used that may have triggered this state
1. Use RetroArch with Mini vMac core to render classic Mac games
2. Exit back to Steam gaming mode
3. Use Steam normally for a few minutes
4. Reboot Steam Deck
5. Gaming mode displays for ~5 seconds, then screen goes black
6. Issue persists on subsequent reboots

## Symptoms
- Screen works briefly after boot (Steam UI visible and responsive)
- After ~5 seconds, display goes completely black
- Backlight remains on (brightness at 3947/4095)
- System processes continue running normally (confirmed via SSH)
- gamescope process running (PID shows active)
- Steam processes running (28 processes confirmed)
- Button inputs have no effect (Steam button, power button, etc. do not wake display)
- Only fix: SSH in and run `pkill -9 steamwebhelper && pkill -TERM steam`

## Root Cause (Confirmed via Logs)
steamwebhelper encountered fatal X11/GLX rendering errors and stopped updating the display.

**Error logs from `/home/deck/.local/share/Steam/logs/webhelper.txt`:**

```
[2025-10-04 14:17:06] Webhelper: An X Error occurred on display 0x7fa8cc209f40
[2025-10-04 14:17:06] X Error of failed request: BadMatch (invalid parameter attributes)
[2025-10-04 14:17:06] Major opcode of failed request: 142
[2025-10-04 14:17:06] Serial number of failed request: 129

[2025-10-04 14:17:06] Webhelper: An X Error occurred on display 0x7fa8cc209f40
[2025-10-04 14:17:06] X Error of failed request: BadDrawable (invalid Pixmap or Window parameter)
[2025-10-04 14:17:06] Major opcode of failed request: 150
[2025-10-04 14:17:06] Resource id in failed request: 0x2c00020
[2025-10-04 14:17:06] Serial number of failed request: 130

[2025-10-04 14:17:06] Error: AcquirePixmap: failed to create glx pixmap for window: 0x1000016

[2025-10-04 14:17:06] Webhelper: An X Error occurred on display 0x7fa8cc209f40
[2025-10-04 14:17:06] X Error of failed request: GLXBadPixmap
[2025-10-04 14:17:06] Major opcode of failed request: 150
[2025-10-04 14:17:06] Serial number of failed request: 132

[2025-10-04 14:17:06] Webhelper: An X Error occurred on display 0x7fa8cc209f40
[2025-10-04 14:17:06] X Error of failed request: BadPixmap (invalid Pixmap parameter)
[2025-10-04 14:17:06] Major opcode of failed request: 54 (X_FreePixmap)
[2025-10-04 14:17:06] Resource id in failed request: 0x2c00020
[2025-10-04 14:17:06] Serial number of failed request: 133
```

## Technical Analysis
steamwebhelper's graphics compositor failed when attempting to:
1. Create a GLX pixmap (off-screen drawable surface)
2. Render to window ID 0x1000016
3. This resulted in BadDrawable, BadMatch, and GLXBadPixmap errors
4. After these errors, steamwebhelper stopped rendering frames → black screen
5. steamwebhelper process remained running but non-functional

**System logs showed no crashes:**
- No kernel panics or GPU driver errors
- gamescope continued running normally
- Display hardware functional (xrandr showed active 1280x800 output)
- Only error in dmesg: `[drm] Failed to add display topology, DTM TA is not initialized` (minor, unrelated)

## Workaround
**If you have SSH access:**
```bash
ssh deck@<steam-deck-ip>
sudo pkill -9 steamwebhelper && sudo pkill -TERM steam
```
Steam will automatically restart and display will work normally.

**If you don't have SSH access:**
1. Hard power off (hold power button 10+ seconds)
2. Boot into Desktop Mode (hold Volume Down during boot, select Desktop Mode)
3. Desktop Mode bypasses the broken steamwebhelper instance

## Possible Triggers
- Heavy I/O load on SD card (RetroArch was scanning 12,584 ROM files)
- Concurrent rendering from RetroArch/libretro cores (Mini vMac in this case)
- Possible resource exhaustion or race condition in gamescope/Xwayland
- Previously had dock connected (disconnected before issue occurred)

## Additional System Information
**Display configuration:**
- Brightness: 3947/4095 (96%)
- Resolution: 1280x800
- Display server: gamescope with Xwayland

**Running processes at time of failure:**
- gamescope PID 1117 (2.5% CPU, running normally)
- 28 Steam-related processes running
- No RetroArch processes (had been killed before reboot)

**Decky Loader plugins active:**
- SteamGridDB
- EmuDecky
(Both showed warnings about legacy method calls)

## Expected Behavior
steamwebhelper should gracefully handle GLX/X11 errors without causing permanent display failure, or at minimum provide a recovery mechanism accessible from the device itself.

## Request
1. Add error handling in steamwebhelper for GLX pixmap creation failures
2. Provide a hardware button combination to force-restart steamwebhelper/Steam UI
3. Investigate race conditions between gamescope and steamwebhelper during high system load

## Reproducibility
Unknown - issue started after specific usage pattern but root cause (GLX errors) suggests potential race condition or resource leak in steamwebhelper's graphics code.

in this state, though, reboots, hard reboots, would always enter this state shortly after boot.