-
-
Notifications
You must be signed in to change notification settings - Fork 0
Troubleshooting
Things that go wrong on a running SynapseOS, and what to do about them. Symptom first.
Working on the system rather than with it? The engineering counterpart is Development Notes.
The one habit worth having: don't trust a status command. Most of what breaks here breaks quietly — a service that reports success while doing nothing, a switch that is on with nothing behind it. When something "works but doesn't", go and look at the thing that is actually running.
| Question | Don't ask | Ask |
|---|---|---|
| Is the AI actually on my GPU? | the log line |
grep -c nvidia /proc/$(pidof synapd)/maps — 0 means CPU |
| Is the kernel module loaded and current? | dkms status |
modinfo synapse_kmod | grep vermagic vs uname -r
|
| Is my package actually installed? | that you built it |
pacman -Q synui — compare the pkgrel |
| Is a setting live? | the panel | the state file under ~/.config/synui/
|
| Is a service running the config I edited? | the file you edited | systemctl show -p FragmentPath <unit> |
Everything should be up after boot:
systemctl status synapd synguard synnet
lsmod | grep synapse_kmod
cat /sys/kernel/synapse/statusRun synui-sound with no arguments and read the theme line.
theme alsa <-- NOT a sound theme, nothing will play
pick one of: freedesktop ocean
If you see that, the selected directory is not a sound theme — it holds no
XDG-named samples, so every lookup misses and every event is silent no matter
what its switch says. /usr/share/sounds/alsa is the usual culprit: it is nine
channel-test .wav files dropped there by alsa-utils.
synui-sound themes # what you can actually pick
synui-sound theme freedesktopIf the theme is fine but one event is silent, check its sample column — a
(not in <theme>) there means that theme simply doesn't ship a sample for it.
Pick one it does have:
synui-sound samples
synui-sound sound login bellAnd if nothing plays at all, confirm the pieces are installed:
sudo pacman -S sound-theme-freedesktop libcanberra
synui-sound test login # plays regardless of any switchTwo independent causes, both quiet:
-
ALSA's
defaultdevice is unrouted. Usuallypipewire-alsais missing, or the default card genuinely has no playback device. Test withaplaydirectly and check its exit status — a lot of software ignores it and turns a hard failure into silence. -
PipeWire clients killed by the kernel. If
xdg-desktop-portalwas started beforertkitwas installed, it holds a cachedRTTimeUSecMax=0: clients get realtime priority with a zero time budget and the kernel duly kills them. Restart the portal (or reboot) after installing rtkit.
Almost always: what you downloaded is a source tree, not a built theme.
Cursor sites ship both, and they look identical from the outside. A theme has a
cursors/ directory with files in it; a source tree has a makefile and needs
compiling.
Don't extract it into ~/.local/share/icons by hand — that leaves a directory
that nothing will ever see and nothing explains. Use the installer, which tells
you which one you have:
synui-cursor install ~/Downloads/whatever.tar.gzIf it is a source tree, it stages it and prints the two commands to finish
(build, then install). Building needs xorg-xcursorgen and imagemagick,
and it runs that archive's own makefile as you — so it is a separate, explicit
command. Only do it for an archive you trust.
Games and other Xwayland clients read the theme from somewhere else. synui-cursor set writes all five locations, so use it rather than setting XCURSOR_THEME by
hand:
synui-cursor set <theme> 24A giant pointer in one app specifically means XCURSOR_SIZE is unset for it:
libXcursor then computes a size from the X screen, and a multi-monitor Xwayland
screen is thousands of pixels wide.
Already-running apps keep the old cursor until they restart. Nothing can change that — log out and back in if you want everything consistent.
synui starts it once and does not respawn it, so if it was killed it stays gone:
synui-bar &If it starts but the tray is empty, tray apps register with whichever process owns the tray service — restart the app after the bar, not the other way round.
If you have the quick-launch widget on, the desktop right-click menu is unreachable underneath it — that widget accepts clicks by design. Turn it off, or right-click somewhere else:
synui-widgets launcher off
synui-widgets all off # clear the desktop entirelySuper+Shift+A does the same from a panel.
The bar reserves its strip slightly after startup, so a very early layout can place icons where the bar is about to be. Toggle icons off and on, or re-arrange them from the desktop right-click menu.
Firefox doesn't use server-side decorations, so it keeps an invisible margin
around itself that swallows the resize grab. clip_csd_margin = on (the default)
crops it. If you turned it off, that's the trade.
That is the application's own shadow, not synui's. Same cause as above: apps
that ignore server-side decorations paint their own. clip_csd_margin = on makes
every window use synui's. See Window Effects.
Window effects ship off on a fresh install. Turn them on with Super+E, or
in ~/.config/synui/synuirc. Note that blur only shows where a window is
translucent, so transparency = on is usually what you actually want first.
Cosmetic, and it clears on the next repaint. Toggling blur off and on resets it.
The engine cannot re-create a layer surface it has lost, so it stays running and paints nothing while synui's own wallpaper shows through. synui restarts it for you on resume; if it ever doesn't:
synui-wpengine restoresynui-wpengine status will show it running with the saved wallpapers listed —
running is not the same as painting, which is exactly what makes this one
confusing. See Wallpapers.
Web-type wallpapers do not work. They initialise and then render an empty
texture — an upstream bug in the engine's CEF→GL path, not something a setting
here fixes. synui-wpengine list shows each wallpaper's type; pick a scene or
video one.
In order:
pacman -Q linux-wallpaperengine # is the package installed?
ls ~/.local/share/Steam/steamapps/common/wallpaper_engine/assets # is WE installed?
synui-wpengine list # does it see subscriptions?Wallpaper Engine itself must be installed through Steam — the engine reads its
assets/ tree, which is not redistributable and so is not part of any package.
Entries that are subscribed but never appear are usually presets or
asset packs rather than wallpapers; those are skipped deliberately.
That is ~/.config/synui/wallpaper.state doing its job — the picker's choice
overrides the config file on purpose. Delete it to hand control back:
rm ~/.config/synui/wallpaper.stateYou have a per-monitor override. Open Super+W, press Tab until the scope
says All monitors, and pick — that clears every override at once.
Set a primary output — Super+D then p, or primary=1 in
~/.config/synui/outputs.conf. Without one, SDL falls back to connector order.
Some games' "fullscreen" is borderless windowed, which never tells the
compositor it is fullscreen, so synui correctly tiles it. Either set true
fullscreen in the game (Doom KEX: v_windowmode=2, not 1), or force it with
Super+Shift+F.
Usually the game, not the compositor. Unity titles persist a screen-resolution index, not a resolution — move the game between monitors with different mode lists and the saved index can point outside the new list, giving a 1×1 viewport inside a correctly sized window. Delete or fix the game's prefs entry.
A blank window at the right size is a client resolution bug far more often than a compositor bug.
MANGOHUD=1 only hooks Vulkan. OpenGL games need the wrapper:
mangohud %command%
in the launcher's command-line options.
It reads the monitor's EDID rather than the plane's bit depth, so a 10-bit monitor that is not actually HDR is reported honestly. Full HDR10 output is not implemented yet.
If the editor is DaVinci Resolve, it most likely imported as media offline rather than failing outright — and the file is fine. It plays in any ordinary player.
The free edition of Resolve on Linux decodes neither H.264 nor AAC, which is exactly what a normal recording contains. That is a licensing limit inside Resolve, not a missing codec on your machine, so no package you install will change it. Convert the recording instead:
syn resolve transcode ~/Videos/synui-20260101-120000.mp4That writes a DNxHR .mov into a DNxHR/ folder beside the original — import
that one. --profile dnxhr_lb is proxy-grade and much smaller, --profile dnxhr_hq is heavier for grading, and --fps overrides the rate it conforms to.
DaVinci Resolve covers the rest — installing it, and the
OpenCL dependency that is the usual reason it installs fine and then will not
start at all.
If you know before you press record that the take is going into an edit, skip the conversion entirely: Control panel ▸ Sound ▸ Record for editing captures that format directly. It also avoids compressing the footage twice, which fine text and sharp UI edges will show. Expect roughly 1 GB per minute, and turn it back off when you are done.
Recordings made before SynapseOS 0.2.7 were captured at a variable frame rate — a frame only when the screen changed. They play correctly, but they have no single frame rate for a timeline to sit on, so an editor conforms them on import and drops frames unevenly doing it.
Nothing can put those frames back, but syn resolve transcode will at least
conform the clip to a real rate uniformly rather than leaving the editor to
guess. New recordings are captured at a constant 60 fps and do not have the
problem; SYNUI_RECORD_FPS changes that rate if you want your display's own.
Control panel ▸ Sound ▸ Record for editing is on. The row itself tells you
which mode you are in — it reads DNxHR ~1.1 GB/min when enabled and
off (H.264 mp4) when not.
That format exists to be edited, not stored or shared. An ordinary recording of
the same length is a tiny fraction of the size, so switch back once the edit is
done and convert individual takes with syn resolve transcode as you need them.
It shouldn't — synui holds an idle inhibit while audio is playing. If it still
blanks, the player may not be routing through PipeWire. Adjust or disable the
timeouts in Super+P.
Check Super+P; a stuck idle inhibitor from a crashed app can also hold it
awake. Restarting the offending app clears it.
The nvidia-suspend, nvidia-resume and nvidia-hibernate services must be
enabled. They preserve video memory across suspend; without them the GPU
comes back with nothing to display.
systemctl status nvidia-suspend nvidia-resume nvidia-hibernate
sudo systemctl enable nvidia-suspend nvidia-resume nvidia-hibernateIf the lock screen was up when it suspended, the lock pane may not have been re-added for the output. Type your password blind and press Enter — it usually unlocks. A monitor plugged in during a lock is the common trigger.
If VT switching is unavailable there is no way back in but a hard reboot, and
repeated failed password attempts make it worse: pam_faillock starts locking
the account after a few tries, so retrying faster locks you out for longer.
Stop retrying. Reboot, and if the account is locked:
faillock --user <name> --reset # from a root shell or recoveryYour local package database is stale relative to the mirror — the version your DB wants has already been superseded and deleted. It is not a bad mirror, and switching mirrors won't help.
sudo pacman -SyuCheck what's in the upgrade set first. If a kernel, NVIDIA driver or DKMS bump is in there, expect module rebuilds — don't start it five minutes before you need the machine.
modinfo synapse_kmod | grep vermagic # must match `uname -r`
sudo dkms autoinstalldkms status reporting "installed" is not a health check — it only confirms
a .ko exists somewhere, not that it matches the running kernel.
systemctl status synapd
grep -c nvidia /proc/$(pidof synapd)/mapsA GPU-linked synapd cannot start at all if the driver it was built against is
missing or was just upgraded out from under it. Switching back to CPU gets you
running again while you sort the driver out:
synui-ai-backend cpuNothing appears and nothing errors, because there is no terminal to print to. Two usual causes: no polkit authentication agent in the session to prompt you, and — for X11 apps — root not being allowed to open the Xwayland display. Reproduce it from a terminal before concluding the launcher is broken; you will usually get the real error immediately.
Which application opens a folder is decided by mimeapps.list, not by which
programs are capable of it. SynapseOS ships its answer in
/usr/share/applications/mimeapps.list — the distribution default, which is
synfiles — and any choice of your own outranks it, because yours lands in
~/.config/mimeapps.list.
xdg-mime query default inode/directory # what actually runs
xdg-mime default org.kde.dolphin.desktop inode/directory # prefer Dolphin
xdg-mime default synfiles.desktop inode/directory # prefer FilesDeleting the inode/directory line from ~/.config/mimeapps.list falls back to
the system default rather than to nothing.
If a folder opens in a terminal, that is the same mechanism with no entry
anywhere: with nothing to consult, the winner comes from mimeinfo.cache — that
is, "whichever installed program declared the type first" — and a terminal
emulator that declares inode/directory can win it. Setting a default fixes it
permanently.
KDE's application index is empty. SynapseOS ships
/etc/xdg/menus/applications.menu; if it is missing or malformed the index can't
build. Rebuild it with kbuildsycoca6. Files does not use that index — it
reads mimeinfo.cache itself — so a difference between the two menus is this,
not a missing application.
Images, MP4 and MOV are read by Files itself. Matroska (.mkv), WebM and
AVI are handed to ffprobe, which is an optional dependency: synpkg install ffmpeg and the row appears. Without it there is no row rather than a guessed
one.
The session's PATH is built in more than one place and ~/.local/bin isn't
always on it. Log out and back in after changing shell profiles, or call it by
full path to confirm that's the problem.
Some tray applications tie themselves to a login record and exit when the last one goes away. Run it as a supervised user service instead of from a terminal.
Check that the driver's filter and its libraries are where CUPS expects them, and
that cups.service is running. journalctl -u cups names the missing piece.
Keys can only be enrolled while the firmware is in Setup Mode, and rebooting will never put it there — whatever the error message implies. You have to clear the Platform Key from the BIOS/firmware menu yourself.
syn-secureboot enroll checks for real Setup Mode before trying, so it tells you
this instead of failing obscurely. See Secure Boot.
If the passphrase is right and it still fails, the LUKS header may be damaged —
and a damaged header means the data is unrecoverable even with the correct
passphrase. This is what syn-crypt backup-header is for; take one now if you
haven't.
syn-crypt status
syn-crypt backup-header /path/on/removable/media/luks-header.imgKeep the backup off the encrypted disk.
Two commands worth attaching to any report:
systemctl --failed
journalctl -b -p err --no-pager | tail -50Note that the compositor's own output does not go to the journal — if synui
or something it launched is misbehaving, the error is on tty1
(Ctrl+Alt+F1).
See also: Installation, Commands, Development Notes.
Using it
- Installation
- Updating
- Software
- Files
- Keybindings
- Commands
- Nix
- Gaming
- DaVinci Resolve
- Secure Boot
- Troubleshooting
Customising it
Components
Apps
Hacking on it