Troubleshooting

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.

---

Quick checks

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/status

---

Sound

Event sounds are switched on and nothing plays

Run 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 freedesktop

If 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 bell

And 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 switch

No audio anywhere, or audio apps keep dying

Two independent causes, both quiet:

• ALSA's default device is unrouted. Usually pipewire-alsa is missing, or the default card genuinely has no playback device. Test with aplay directly 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-portal was started before rtkit was installed, it holds a cached RTTimeUSecMax=0: clients get realtime priority with a zero time budget and the kernel duly kills them. Restart the portal (or reboot) after installing rtkit.

---

Cursors

I installed a cursor theme and it isn't in the picker

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

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

The cursor is right on the desktop but wrong (or huge) in a game

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> 24

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

---

The desktop

The bar is gone

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.

Part of the desktop won't accept clicks

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 entirely

Super+Shift+A does the same from a panel.

Desktop icons sit under the bar

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 can't be resized by dragging its edges

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.

A window has a heavy, square-cornered shadow unlike everything else

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.

Everything looks flat — no blur, no shadows

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.

A window leaves a ghost outline after resizing

Cosmetic, and it clears on the next repaint. Toggling blur off and on resets it.

---

Wallpapers

My Workshop wallpaper is gone after waking from standby

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 restore

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

A Workshop wallpaper is just black

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.

The picker doesn't list my Workshop wallpapers

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.

My wallpaper reverts every login, ignoring synuirc

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

One monitor has the wrong wallpaper

You have a per-monitor override. Open Super+W, press Tab until the scope says All monitors, and pick — that clears every override at once.

---

Displays and games

A game opens on the wrong monitor

Set a primary output — Super+D then p, or primary=1 in ~/.config/synui/outputs.conf. Without one, SDL falls back to connector order.

A game won't go fullscreen — it stays tiled

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.

A game window is the right size but renders nothing

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 never appears

MANGOHUD=1 only hooks Vulkan. OpenGL games need the wrapper:

mangohud %command%

in the launcher's command-line options.

The display panel says a monitor isn't HDR

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.

---

Power, locking and suspend

The screen blanks while I'm watching something

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.

The screen never blanks

Check Super+P; a stuck idle inhibitor from a crashed app can also hold it awake. Restarting the offending app clears it.

Black screen after resuming from suspend, on NVIDIA

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-hibernate

The screen is black after waking, but the machine is alive

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

I'm locked out and can't switch to a text console

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 recovery

---

Updates and packages

pacman -S 404s while fetching a dependency

Your 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 -Syu

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

After a kernel upgrade the kernel module won't load

modinfo synapse_kmod | grep vermagic     # must match `uname -r`
sudo dkms autoinstall

dkms status reporting "installed" is not a health check — it only confirms a .ko exists somewhere, not that it matches the running kernel.

The AI stopped responding after an upgrade

systemctl status synapd
grep -c nvidia /proc/$(pidof synapd)/maps

A 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 cpu

---

Apps and integration

An app that needs root does nothing when launched from the menu

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

"Open With" is empty in Dolphin and every file opens the chooser

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.

A command in ~/.local/bin isn't found in the session

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.

A tray icon disappears when I close my terminal

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.

The printer installs but prints nothing

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.

---

Boot and Secure Boot

Secure Boot key enrollment fails no matter how many times I reboot

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.

I encrypted the disk and now I can't unlock it

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

Keep the backup off the encrypted disk.

---

Still stuck?

Two commands worth attaching to any report:

systemctl --failed
journalctl -b -p err --no-pager | tail -50

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