-
-
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.
You do not need the desktop for that. From a text console (Ctrl+Alt+F2) or
over SSH:
synfiles tui ~Arrow keys move, → opens, ← goes up, t trashes, m and y move and copy,
q quits. It is the same file manager as the window — the same trash, the same
journal, so synfiles undo afterwards reverses what you did here. It never turns
on mouse reporting or an alternate screen, so a session interrupted halfway
cannot leave your shell reading pointer movement as typed input.
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.
If a screen was switched off from Super+D rather than unplugged, windows
whose saved position was on it could still be placed there — the application
opened, took the keyboard, and was invisible. Fixed in synui 0.1.0-376: a
disabled output is detached from the layout and anything on it is swept to a
surviving screen.
If it happens on an older build, re-enable the screen, move the window, and
switch the screen off again — or delete the saved geometry for that application
(~/.config/synui/geom.state).
It renders at 640×480 or 1024×768 and has no idea what a 1440p monitor is.
syn-arcade fit wraps it in gamescope, which gives it a display of exactly the
size it expects and upscales the result — see
Gaming.
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.
Two reasons, and the first is new since 0.2.9.4.
MANGOHUD=1 is no longer exported for the session. It used to be, and that
one variable loaded the overlay layer into every Vulkan client on the machine —
a browser, a video player, any Qt application that touched QtMultimedia — where
on AMD it segfaults the client inside its own vkCreateDevice hook. The overlay
comes from the launcher now:
syn game ./game.x86_64 # or, as a Steam launch option:
syn game -- %command%
syn game hud on puts the old session-wide behaviour back if your machine has
never seen that crash; syn game hud says which it currently is.
And MANGOHUD=1 only ever hooked Vulkan. OpenGL games need the wrapper
either way:
mangohud %command%
in the launcher's command-line options — which is what syn game does for you.
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. Plenty of 10-bit panels are not HDR panels.
The column shows HDR10 (—) when the panel advertises HDR over a link that
will not carry it. synctl hdr says which part was refused:
DP-3 pq=yes bt2020=yes image_description=yes … pq_lut=yes sdr=yes capable=yes
image_description is whether the display can be told it is receiving HDR10,
pq_lut whether the desktop can be mapped into it, and sdr whether it can be
taken back out again — a monitor that fails the last one is never offered the
mode, because a mode you cannot switch off is worse than one you never had.
The usual cause is bandwidth: HDR10 also asks for 10-bit colour, and a DisplayPort link with the headroom for that at 1440p120 may not have it at 4K144. Try a lower refresh rate, or a cable rated for the mode you are in.
The colours are being stretched across a wider gamut than they were drawn for.
This happens on a monitor that will only accept a BT.2020 container: the
transfer curve is mapped in the display hardware and the primaries cannot be,
so reds and greens run wide. The detail line under the monitor list says so when
it is what happened. Switch HDR off with Shift+D if you would rather have
correct colour than correct brightness.
Move the SDR white level with [ and ] in the display panel, or
synctl hdr white <output> <cd/m²>. It sets where an ordinary white window
lands on HDR's absolute scale; 203 is the broadcast reference and the default,
and the useful range is roughly 150–300 depending on the panel and the room.
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 — a video player asks synui to stay awake, over the
org.freedesktop.ScreenSaver bus name or the Wayland idle-inhibit protocol.
Firefox, Chrome, mpv, VLC and Steam all do. If it still blanks, the player is
not asking; adjust or disable the timeouts in Super+P.
Music alone does not keep the screen awake, on purpose. Sound coming out of the speakers says nothing about whether anyone is at the desk, so playback by itself is not an idle inhibit. If you want the screen up while you listen, hold one yourself:
printf 1 | /usr/lib/synui/synui-idle-inhibit # held until you kill itCheck Super+P first. Failing that, an app is holding an idle inhibit — a
crashed video player is the usual one, and restarting it clears the inhibit.
To see whether anything is holding one, watch the journal while the machine sits idle:
journalctl -f | grep -E 'synui: (screensaver|power):'An inhibit that is taken and never released is the bug; synui logs both halves
with the app's own name. Note that systemd-inhibit --list will not show it —
those are logind's sleep inhibitors, which are a different mechanism from the
one the screen blanker uses.
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 recoveryThe account is locked, not the password wrong. pam_faillock locks an account
for 10 minutes after 5 failed logins (3 on an install from before September
2026), and the lock covers sudo, the login screen and the lock screen alike —
so a correct password is refused everywhere, with nothing saying why. Check:
journalctl -b | grep -E 'temporarily locked|conversation failed|incorrect password'Stop trying for ten minutes. Every attempt against a locked account used to count as another failure and restart the ten minutes. Then type the password once. A reboot also clears it — the lock lives in memory.
Before synui 0.1.0-613 a password prompt that was never answered counted as a
failed login too: a sudo with no terminal to ask on, a Ctrl+C at a sudo
prompt, and — with the fingerprint turned on at the login screen — the login
screen itself, every ten seconds it sat idle. Since 613 only a wrong password
counts. The finger still worked at the login screen through all of it, which
is why the first thing that failed was sudo.
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 -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 cpuThat is syntty, SynapseOS's own, and it has been the default since synui
0.1.0-359 — see Terminal. foot ships alongside it as the
rescue terminal. kitty is not installed any more (syn-install 0.1.0-100):
synpkg install kitty puts it back, and terminal = kitty in
~/.config/synui/synuirc then makes it the one Super+Return opens.
Fixed in synui 0.1.0-374. The terminal key ran a fallback chain
(syntty || kitty || foot || …) so that a machine whose terminal package failed
to install still opens something — but || means "the previous one exited
non-zero", and a terminal's exit status is the exit status of the shell inside
it. Exiting a shell after a failed command therefore looked like a terminal that
would not start, and the next one on the list opened.
Fixed in synpkg 0.1.0-29 / synui 0.1.0-369. Two separate faults: kitty was
still load-bearing months after it stopped being the default (synui's config, the
--hold call sites), and the window swallowed the failed transaction instead of
saying why. Both are gone — the last --hold pin moved to syntty in 0.1.0-370.
Three different things that look identical:
-
The stick's write-protect switch is set.
syn-diskschecks before the dry run now and says so, instead of failing atmke2fswith "Read-only file system while setting up superblock" — a sentence that reads like a dead stick and means a switch on the side of one. - The stick latched itself read-only mid-write. Some cheap drives answer "write protect off" at plug-in and flip after the first failed write. There is no switch to look for; the drive is failing.
-
It formatted fine and will not mount. Check the filesystem is one this
kernel can mount — a stick formatted exFAT on a kernel with no exFAT support
is a perfect format that mounts nowhere.
syn-disksonly offers filesystems it can both create and mount.
A stick you format now also belongs to you afterwards: mkfs runs as root
through polkit, so the new filesystem's root directory used to be root-owned and
the drive came back mounted and unwritable to whoever had just formatted it.
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.
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.
Waydroid, libvirt, Docker and Podman all work the same way: they hang a bridge
off this machine, run a DHCP and DNS server on it, and hand the guest an address
in a private range. The firewall trusts private addresses, so everything the
guest sends is accepted — once it has one. The request that asks for one is
not: it is sent from 0.0.0.0, before the guest has any address at all, and the
default-drop policy eats it.
The guest then comes up with no network, and nothing in any log mentions the firewall. It looks like a broken container, a DNS problem, or a bad bridge.
Name the bridge and it works:
sudo synnet --trust-if waydroid0 # libvirt: virbr0 · Docker: docker0 · Podman: podman0
synnet --status # lists what is trustedThat takes effect immediately and is remembered in /etc/synnet/trusted-ifaces.
Settings ▸ Network shows the same list under container links.
The bridge does not have to exist yet — these interfaces are only created when the container starts, and the rule is matched by name, so it starts working the moment the bridge appears.
⚠ The container runtime's own firewall rule does not cover this. Waydroid, for
one, inserts an iptables rule to accept DHCP on its bridge, and it makes no
difference: that lands in a separate chain, and where two filters disagree the
stricter one wins. Seeing the runtime's ACCEPT rule in iptables -L is not
evidence the packet gets through.
⚠ Editing /etc/synnet/trusted-ifaces by hand does not change the running
firewall. The daemon only rebuilds a chain that has gone missing; one that is
merely out of date looks healthy to it. Run sudo synnet --firewall after
editing, or use --trust-if, which does it for you. Settings ▸ Network warns
when the two have drifted apart.
First check that the network is trusted. The firewall lets other devices in only on a network you trusted; on any other network — including your own, if nobody has said so yet — only replies, ping and DHCP get through.
synnet --networksIf your network reads NOT trusted, trust it in Settings ▸ Network, or:
sudo synnet --trust-network "<the network's name>"On a trusted network the firewall accepts everything from the other devices on
it, so if the network is trusted and it still fails, look at the service.
Unsolicited traffic from a public address is dropped on every network; to let
one port in from anywhere, see synnet --open in
Commands.
synnet --statusIt answers without root, because the daemon publishes what it applied. Settings ▸
Network reports the same thing, plus whether synnet itself is running — the
rules outlive the daemon, so a stopped synnet leaves the last ruleset loaded
and stops maintaining it.
⚠ If it says not asserted on a machine that is otherwise fine, the running
daemon is probably older than the installed binary: syn-update replaces the
file but does not restart the unit. sudo systemctl restart synnet.
If you joined the image from .part* files, suspect the join before the
stick or the machine — and on Windows especially. You can skip the join
entirely: soslinux.org serves the ISO as one
file, and the parts exist only because GitHub caps a release asset at 2 GiB.
The two usual join mistakes both produce a file that looks finished:
-
copywithout/b. In text modecopystops at the first0x1Abyte, a few hundred KB into the image. You get a short file and no error at all. -
A wildcard source (
copy /b *.part* out.iso).copytakes wildcards in directory order, which is not guaranteed to be sorted. Parts joined out of order give a file of exactly the right size that is corrupt throughout.
Either way the stick may still start to boot and then fail once it reaches the squashfs, which reads as a broken image or bad hardware. Check the ISO against the published checksum before anything else:
(Get-FileHash -Algorithm SHA256 .\SynapseOS-<ver>-x86_64.iso).Hash -eq (((Get-Content .\SynapseOS-<ver>-x86_64.iso.sha256) -split '\s+')[0]).ToUpper()False means re-join it, naming every part in order — see
Installation. On Linux or macOS the same check is
sha256sum -c SynapseOS-<ver>-x86_64.iso.sha256.
If the checksum is right and it still will not boot, the next two things to try are writing with DD Image mode rather than ISO mode (Rufus asks; this is a hybrid image), and switching Secure Boot off — see below.
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
- Welcome Guide
- Updating
- Software
- Files
- Settings
- Calendar
- Editor
- Studio
- Terminal
- Keybindings
- Speech and dictation
- Remote Desktop
- Malware Scanning
- Commands
- Configuration
- Nix
- Gaming
- Big Screen
- DaVinci Resolve
- Secure Boot
- Troubleshooting
Customising it
Components
Apps
Hacking on it