Repository navigation
Troubleshooting
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 curve in the SkillFishOS Control Center's Tuner section (pick the Balanced or Cautious preset, or set the ceiling 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 Control Center's Tuner section and step down one notch (a lower preset, or Suggest UV on the CPU panel). 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, Discover's included. The snapshots in the GRUB menu boot read-only: good for looking around and copying files out, not for going on working. To really go back, from a terminal or a text console (Ctrl+Alt+F3):
sudo skillfish-rollback --elenco # list the snapshots
sudo skillfish-rollback <number> # the "pre" one before the bad update
sudo reboot
sudo skillfish-rollback --annulla undoes the rollback. @home is separate, so your files stay as they are now. See APT Repository.
Symptom: after updating from Discover, Plasma is gone: no desktop, no Dolphin, no Konsole, no Control Center or Hub. Only the Big Picture session is left.
Cause: Debian sid was moving Qt from 6.10 to 6.11 before KDE had been rebuilt for it. apt holds the new Qt back in that situation; Discover (PackageKit) removed about 270 packages instead. See issue #87. Since packages 26.09.41, skillfish-desktop-guard stops any updater from doing this, and since 26.09.42 the Hub removes Discover. Update from the SkillFishOS Hub.
Fix, with snapshots: go back to the snapshot taken right before that update, as in the section above. It is the cleanest way.
Fix, without snapshots: from a text console (Ctrl+Alt+F3), log in and run
curl -fsSLo repair.sh https://skillfishos.com/repair.sh
sudo bash repair.sh
It reads from /var/log/apt/history.log what that update removed, shows what it is going to do and asks before doing it. While Debian is still rebuilding KDE it takes the Qt 6.10 versions from Debian testing through a temporary source, which it removes at the end. It removes nothing, it does not touch /home, and it installs skillfish-desktop-guard. Reboot when it says Done. --dry-run only shows the plan. On systems updated to 26.09.43 or later the same script is installed as skillfish-repair-desktop.
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 --registraIt 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.9-skillfishos/linux-image-7.2.9-skillfishos_7.2.9-1_amd64.deb
sudo dpkg -i linux-image-7.2.9-skillfishos_7.2.9-1_amd64.debUse the file name that matches your kernel — add -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 Test CU in the Control Center's Tuner section 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 clock / undervolt in the SkillFishOS Control Center's Tuner section. See CPU Overclock and Undervolt.
Getting started
Apps
Tuning & hardware
Using it
Developers