Troubleshooting

Troubleshooting

GPU hard-freeze

Symptom: the whole machine hangs — it may still answer ping (the kernel ICMP stack is alive) but SSH and the desktop are dead, and nothing is written to the logs. Only a power-cycle recovers it.

Cause: an unstable GPU clock/voltage transition. On the BC-250 (Cyan Skillfish), 1000 mV is the practical stable ceiling at ~2150–2200 MHz. Pushing the GPU to 2230 MHz @ 1000 mV (undervolted), or using a 2-point voltage curve that jumps straight from idle to the top point, can hard-freeze on a clock transition.

Fix (already shipped): SkillFishOS uses a smooth multi-point voltage curve (350/700, 1500/900, 2000/1000, 2200/1000), caps the GPU max at 2200 MHz @ 1000 mV, and reloads the governor gently (stop → settle → start). If you've manually pushed clocks/voltage, reset the GPU section in the SkillFishOS Tuner (or set the max back to 2200/1000). See GPU Governor and Tuning. Never use power_dpm_force_performance_level / pp_dpm_sclk — they don't control this GPU.

"The system recovered from a freeze" notification

skillfish-base detects an unclean previous shutdown at boot (hard hang → watchdog reset, or power loss), logs it to /var/log/skillfish-freeze.log and notifies you. If you see it more than once, your overclock/undervolt profile is probably unstable: open the SkillFishOS Tuner and step down one notch with the 🎰 wizards. The hardware watchdog reboots the board automatically ~2 minutes into a hard hang.

Display: no signal / black screen after sleep

The BC-250's DisplayPort HPD (hot-plug detect) is broken. A daemon (skillfish-dp-hotswap) watches the EDID and re-detects the monitor. If a screen stays black, unplug/replug the cable or toggle the input.

Audio breaks with a DP→HDMI adapter

Active DP→HDMI adapters can break audio on the BC-250. Prefer a native DisplayPort monitor, or a passive adapter. The audio stack is PipeWire (with Bluetooth).

A bad update broke something

Every apt transaction takes a Btrfs snapshot before and after. Reboot, pick the pre-update snapshot from the GRUB menu, and you're back. @home is separate, so user data is untouched. See APT Repository.

The kernel didn't update

The kernel is delivered by the thin skillfishos-kernel wrapper, which fetches the full image from a GitHub Release out-of-band. If it didn't apply, check systemctl status skillfishos-kernel-install and re-run sudo apt install --reinstall skillfishos-kernel. See Kernel.

An app won't launch from the menu

If you packaged a new app: use an absolute Exec=/usr/local/bin/... and keep a Python reference to the top-level window. See Apps.

Compute Units / instability after 40-CU

Not every chip is stable with all 40 CUs. Run the CU health test in the Tuner to find a bad WGP, or drop back to 32/24 CUs. See Compute Units (40-CU).

CPU throttling / high temps

The skillfish-thermal-guard steps the CPU clock down above 85 °C. If you're throttling, improve cooling or lower the CPU profile / undervolt in the SkillFishOS Tuner. See CPU Overclock and Undervolt.