# nixos-black-screen-debug

> Diagnose NixOS black/blank screen, display output loss, or suspend/resume wake failures on this system. Use when collecting logs around an incident, analyzing KDE/Wayland/X11/GPU power events, proposing mitigations in this repo, or maintaining a running troubleshooting log.

- Author: mike
- Repository: mgwilt/nixos-config
- Version: 20260122103536
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/mgwilt/nixos-config
- Web: https://mule.run/skillshub/@@mgwilt/nixos-config~nixos-black-screen-debug:20260122103536

---

---
name: nixos-black-screen-debug
description: Diagnose NixOS black/blank screen, display output loss, or suspend/resume wake failures on this system. Use when collecting logs around an incident, analyzing KDE/Wayland/X11/GPU power events, proposing mitigations in this repo, or maintaining a running troubleshooting log.
---

# NixOS Black Screen Debug

## Overview

Collect targeted logs for black screen/wake issues, decide whether the incident is a suspend/resume problem or a display/compositor output loss, and keep a persistent troubleshooting log at `references/issue-notes.md`.

## Workflow

1. **Pin the incident time**
   - Ask for the exact time window and timezone; restate as absolute timestamps.
   - Identify the boot index with `journalctl --list-boots`.

2. **Classify the failure mode**
   - **No suspend/resume events** near the time → likely compositor/output loss (Wayland/X11, KWin, DRM/DPMS/hotplug).
   - **Suspend entry but no resume** → hang during suspend/resume.
   - **Resume entry with errors** → device/driver resume issues (USB, GPU, ACPI, etc.).

3. **Collect logs**
   - Use `scripts/collect-display-incident.sh` (preferred) or run manual `journalctl` filters.
   - Always capture **system**, **kernel**, and **user session** logs for the time window.

4. **Analyze**
   - **Display stack:** `kscreenlocker`, `kwin_wayland`, `plasmashell`, `kscreen`, `powerdevil`, `sddm`, `Xorg`, `xdg-desktop-portal*`, `egl`, `drm`.
   - **Kernel/driver:** `nvidia`, `i915`, `amdgpu`, `drm`, `acpi`, `pcie`, `usb`.
   - Look for hotplug/DPMS events, output loss, or GPU resets.

5. **Record a dated entry**
   - Append findings and any changes to `references/issue-notes.md`.
   - Include: time window, boot index, commands run, observations, hypothesis, changes, result.

6. **Propose mitigations (one at a time)**
   - Prefer reversible, minimal changes.
   - Track every change in the notes and link to the edited file path.

## Log Collection

Preferred script:

```bash
/home/mike/.codex/skills/nixos-black-screen-debug/scripts/collect-display-incident.sh \
  --boot -1 --start "2026-01-22 09:55:00" --end "2026-01-22 10:05:00"
```

Manual quick filters:

```bash
journalctl -b -1 -S "YYYY-MM-DD HH:MM:SS" -U "YYYY-MM-DD HH:MM:SS" --no-pager
journalctl -b -1 -k -S "..." -U "..." --no-pager
journalctl --user -b -1 -S "..." -U "..." --no-pager
journalctl -b -1 --no-pager | rg -i "suspend|sleep|hibernate|resume|wake|wakeup|powerdevil|kscreen|kscreenlocker|kwin|plasmashell|wayland|xorg|drm|nvidia|i915|gpu|egl|display|output|dpms|hotplug|udev|acpi"
```

## Notes

- Update `references/issue-notes.md` after **every** investigation or config change.
- Keep entries concise but concrete (timestamps, boot index, observed log lines, and outcomes).

## Repo Conventions

- Nix files: 2-space indentation, braces on their own lines.
- Prefer declarative settings in `configuration.nix` or local modules.
- Avoid editing `hardware-configuration.nix` unless hardware-driven.