steamify-cachyos/TROUBLESHOOTING.md

Troubleshooting

See TECHNICAL.md for how each part works.

Where are the errors of the quiet steps?

Steps that may fail without it mattering (stopping a service that isn't running, removing a package that isn't installed) don't show their errors in the wizard. They are kept in ~/.local/state/steamify/log/steamify.log (the last 512 KB), with the command and its exit status: attach it when you ask for help.

Gaming mode shows a black screen or keeps restarting

Press Ctrl+Alt+F3, log in with your username and password, and run:

sudo /usr/lib/steamos/steam-set-session plasma.desktop && sudo systemctl restart display-manager

That takes you back to the desktop. Gamescope sessions that fail to start are restarted right away (Relogin=true), which is why it can loop.

Something is set up wrong

Run the wizard again and press a in the menu to re-apply everything that's on (also useful after a CachyOS update). To undo a part, untick it.

"Target OS name ... not found in /boot/limine.conf"

limine-snapper-sync finds the boot entries by the OS name. Steamify never changes that name (it only adds version keys to /etc/os-release), and pins TARGET_OS_NAME="CachyOS" in /etc/default/limine. If you see this message, check that PRETTY_NAME in /etc/os-release still says CachyOS, or set TARGET_OS_NAME in /etc/default/limine to the name your boot entries use.

The LED bar on the Steam Machine stays dark

Restart once more; a freshly installed driver often needs a reboot. The menu shows per kernel whether the LED driver is built, and whether it's loaded. Still dark:

dkms status
ls -l /sys/class/leds/valve-leds*/
sudo dmesg | grep -i valve
cat /var/lib/dkms/leds-valve-dkms/0.1/build/make.log
journalctl --user -b | grep -i led

The TV remote does nothing (HDMI-CEC)

• Turn on CEC in the TV's settings (Sony: BRAVIA Sync, Samsung: Anynet+, LG: SimpLink) and, if it has one, allow the PC to control it.
• Check that the PC has a CEC device, and that cecd runs:

ls /dev/cec*
systemctl --user status cecd
journalctl --user -u cecd -b
cec-ctl -d /dev/cec0 -S        # the devices on the TV's CEC bus (v4l-utils)

No /dev/cec*: your PC has no CEC; a USB CEC adapter (e.g. Pulse-Eight) works. See CEC.md. The Steam Machine wakes up again right after going to sleep, or other devices lose CEC? That happens on SteamOS too; turn HDMI-CEC off in the wizard.

The Steam Machine still reboots when I shut it down

Check that the pinned kernel is installed and running:

uname -r                                   # should be 7.1.6-1-cachyos
pacman -Q linux-cachyos linux-cachyos-headers
grep '^IgnorePkg' /etc/pacman.conf         # should list both packages

Not running it yet? Restart. Not installed? Run the wizard and make sure Pin the kernel under Steam Machine support is ticked. If you have more kernels installed (e.g. the LTS kernel), pick linux-cachyos in the boot menu.

The kernel pin can't download or verify the kernel

The wizard tries this repo's kernel-7.1.6-1 release, then the CachyOS archive and mirror. A file that fails its checksum or CachyOS signature is deleted, so running the wizard again downloads it once more. Offline? Put the four files from the kernel-7.1.6-1 release in /var/cache/steamify/kernel and run it again.