Using it

Troubleshooting

Edit on GitHub · last edited

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)/maps0 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.

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.

See Files ▸ In a terminal.


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-disks checks before the dry run now and says so, instead of failing at mke2fs with "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-disks only 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:

  • copy without /b. In text mode copy stops at the first 0x1A byte, 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). copy takes 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.