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.

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.

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.

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).

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.

Symptom: GRUB appears, you pick SkillFishOS, and the machine stops. A dead underscore, a grub> prompt, or an immediate power-off — but never a kernel message. It looks like the boot loader loaded nothing at all, because that is exactly what happened.

Cause: Secure Boot. SkillFishOS builds its own kernel, and a machine with Secure Boot enabled — how nearly every PC leaves the factory — refuses to run code it has no signature for. GRUB starts (it is signed by Debian), hands over to our kernel, and the firmware stops it there. Nothing is written anywhere, which is why the screen just sits.

Fix today: turn Secure Boot off in your firmware setup, usually under Security or Boot. Nothing else about the machine changes.

Fix, on an installed system: the published kernel is now signed with a SkillFishOS key, and skillfish-secureboot enrols that key in your firmware so Secure Boot accepts it. You do it once:

sudo /usr/local/bin/skillfish-secureboot --registra

It queues the request and explains the rest in your own language; at the next start a blue screen asks you to confirm — the decision stays yours, in front of the machine. From then on SkillFishOS boots with Secure Boot on like any other system.

⚠️ If the kernel was already installed before 27 August 2026, you still have the unsigned one. The kernel package skips the download when that version is already present, so it will not fetch the signed build on its own. Replace it by hand — this is tested, not guessed:

curl -fLO https://github.com/MTSistemi/SkillFishOS/releases/download/kernel-7.2.0-skillfishos/linux-image-7.2.0-skillfishos_7.2.0-1_amd64.deb
sudo dpkg -i linux-image-7.2.0-skillfishos_7.2.0-1_amd64.deb

Use the file name that matches your kernel — -generic, -slim or -x64 if that is what you run. Check what you have with uname -r, and confirm the result with sbverify --list /boot/vmlinuz-$(uname -r): it should name SkillFishOS Secure Boot.

The first boot from a USB stick always needs Secure Boot off, even afterwards: a key cannot be enrolled before the machine has started at least once.

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.

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.

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).

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.