Using it
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
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.
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.
I need to get at my files and the desktop will not start
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.
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 window opens somewhere I cannot see it
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).
An old game is a postage stamp in the middle of the screen
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.
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
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.
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. Plenty of 10-bit panels are not HDR panels.
HDR10 is greyed out on a monitor that says it is HDR
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 desktop looks over-saturated in HDR
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.
The desktop looks washed out or blinding next to HDR video
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.
Screen recording
A screen recording will not open in my video editor
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.mp4
That 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.
An old recording loses frames or stutters when I edit it
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.
My recordings are suddenly enormous
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.
Power, locking and suspend
The screen blanks while I'm watching something
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 it
The screen never blanks
Check 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.
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
sudo rejects a password you know is right
The 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.
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
Super+Return opens a terminal I do not recognise
That 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.
Pressing Ctrl+D in a terminal opens another terminal
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.
The package manager will not remove kitty
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.
A USB stick will not format, or comes back read-only
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.
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.
A folder opens in the wrong application
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 Files
Deleting 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.
"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. Files does not use that index — it
reads mimeinfo.cache itself — so a difference between the two menus is this,
not a missing application.
A video shows no resolution in Properties
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.
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.
Network
A container or virtual machine has no network
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 trusted
That 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.
Something on the local network cannot reach a server on this machine
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 --networks
If 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.
I want to check the firewall is actually on
synnet --status
It 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.
Boot and Secure Boot
The USB stick does not boot, or the live session dies partway in
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.
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.