Troubleshooting
Common Veila setup issues and the quickest ways to debug them
Daemonless locking upgrade
veila lock runs until unlock; use --daemonize --wait-ready for keybinds and sleep hooks. The optional veila.service runs the idle watcher. Restarting it preserves an active lock.
Use veila status and veila reload in your desktop’s Wayland environment. veila stop and veila health were removed. See Lock Control and legacy launcher migration.
Startup fails
Start with diagnostics:
veila doctorThis checks Wayland, logind, config, themes, PAM, process records, service setup, and renderer memory estimates. On Hyprland it also checks crash-recovery policy.
Check the installed version and config:
veila -vveila check-configIf the watcher exits, inspect its journal:
veila logs --journal --idle --lines=80A common cause is an unsuitable logind session. Check the service environment, or launch veila idle from your compositor.
Watcher restarts while locked
Watcher restarts preserve the supervisor, curtain, and password prompt. From a terminal or SSH, veila status should show state=locked and curtain_running=true.
For ownership errors, check the watcher journal and veila logs --file. Do not kill the curtain or start a competing locker.
Direct curtain development tests
Use veila lock normally. Internal veila __curtain --lock tests use an isolated PAM helper and the configured retry backoff, including in the emergency prompt.
Signals and helper/render failures never authorize unlock. Killing a direct curtain can leave the compositor locked without a prompt. Finish through PAM; test signals only in a disposable compositor or with a tested recovery path. Direct curtains cannot receive loginctl unlock-session through a supervisor.
Lock supervisor
veila lock supervises one lock per display. After secure confirmation it handles logind, power actions, fingerprint scans, widgets, and config reloads. Password authentication survives supervisor or provider failures. SIGHUP reloads config; invalid edits keep the current scene. SIGTERM waits for authorized unlock.
Fingerprint scans pause before sleep and restart after resume. Failed scans accumulate until the next lock; at the limit, use your password. Reader, enrollment, or supervisor failures leave password entry available. See Fingerprint settings.
For diagnostics, use foreground stderr or enable [lock] log_to_file = true. The source checkout’s scripts/check-latency tests the public lock command without a daemon.
Lock screen crashed
The supervisor replaces a crashed curtain with the emergency password prompt. Retries wait 0, 1, 2, then at most 5 seconds. Each replacement applies the maximum authentication backoff; wait for the countdown before entering your password. Crashes and signals never unlock the session. Keep the supervisor running.
Direct veila __curtain --lock tests have no recovery supervisor.
- Sweets: opaque covers protect the session during replacement; an abandoned-lock notice may appear after a second. Leave
general.lock_restartunset, or route it through the same supervisor and runtime/display environment. An independent locker can race recovery. - sway: a red fallback may appear until the emergency prompt maps.
- niri: a dark-red fallback may appear until the emergency prompt maps.
- Hyprland: enable
misc:allow_session_lock_restorebefore recovery tests.veila doctorreports its state; check the syntax for your installed Hyprland version. Veila cannot override compositor policy. Real Hyprland recovery is not yet verified.
Repeated refusal messages suggest compositor policy or a competing locker. Check foreground stderr or the configured lock log. If the prompt does not return, report the compositor version and recovery logs; do not launch another independent locker.
Upgrading from veilad
veilad and veilad.service are deprecated aliases. Update existing setups:
-
Replace
exec-once = veiladwithexec-once = veila idle. -
Remove the old service enablement link and enable the current unit.
veila doctorprints the exact link path:rm ~/.config/systemd/user/graphical-session.target.wants/veilad.service systemctl --user enable veila.servicesystemctl --user disable veilad.servicecannot remove that old link because the unit is now an alias. -
Replace removed
veilad --lock-now,--status, and--reload-configflags withveila lock,veila status, andveila reload. -
File logs default to
~/.local/state/veila/veila.log;log_file_pathoverrides it.
Service does not lock
If terminal locking works, compare session environments:
echo "$XDG_SESSION_ID"
systemctl --user show-environment | rg 'XDG_SESSION_ID|XDG_SESSION_TYPE|WAYLAND_DISPLAY|HYPRLAND'Veila needs a local interactive logind session owned by your user. TTY-launched compositors work; remote, background, manager, closing, and unreadable sessions do not.
If XDG_SESSION_ID is unsuitable, Veila tries PID lookup and eligible user sessions, preferring Wayland. Ambiguous matches fail. Use loginctl list-sessions and --session-id=YOUR_SESSION_ID to select explicitly. Debug logs explain rejections:
journalctl --user -u veila.service -b --no-pagerAlternatively, launch the watcher in your compositor session:
exec-once = veila idleLive logs
Run a foreground lock with debug logging, then authenticate to finish:
RUST_LOG=debug veila lockFor the watcher journal:
veila logs --journal --idle --followUseful filters:
veila logs --since=10m
veila logs --curtain
veila logs --idle
veila logs --ui
veila logs --allBy default, logs include the watcher journal and configured lock file. --file or --journal selects one; --idle selects the watcher journal (--daemon is an alias). --curtain and --ui also filter file logs.
--lines applies per source. --since applies only to the journal and conflicts with explicit --file. --follow handles file rotation; Ctrl+C stops the log helpers.
Lock before sleep
Wait for lock readiness before suspending:
veila lock --daemonize --wait-ready && systemctl suspendlock_ready=true confirms compositor lock and UI readiness. If UI readiness times out, an acquired lock stays protected. Duplicate requests reuse it and report:
already_active=trueFingerprint scans release the reader before suspend and restart after resume. For failures, compare the lock log with the system fprintd journal.
Emergency prompt test
Test the minimal secure PAM prompt:
veila lock --force-emergency-ui --wait-readyActivation latency
Show startup, rendering, and lock-confirmation timings:
veila lock --latency-report --wait-readyAdd microsecond precision and gaps between stages:
veila lock --latency-report=verbose --wait-readyPersistent logs
File logging is opt-in. Enable it for detached locks and compositor launchers:
[lock]
log_to_file = true
log_file_path = "~/.local/state/veila/veila.log"Read or follow the file:
veila logs --file
veila logs --file --follow
veila logs --file --lines=100Slow activation
Large blurred panels and high-resolution monitors can delay the full scene. Try smaller panels, less blur, or mode = "solid".
veila doctor estimates renderer memory; debug logs show actual curtain RSS. The estimate includes a temporary redraw buffer, released about 2 seconds after updates stop. renderer.output.N.render_scale_120 uses 120ths (180 = 1.5×), including fractional scaling when supported.
Caches under ${XDG_CACHE_HOME:-~/.cache}/veila fill automatically after UI readiness. No manual prewarm is needed, and unlocking never waits for caching. An early unlock may leave work for the next lock.
Cleanup runs after readiness and every six hours while locked. It removes entries older than 14 days, then the oldest entries over these budgets:
| Cache directory | Contents | Size budget |
|---|---|---|
backgrounds | Rendered backgrounds and panels | 768 MiB |
source-images | Decoded wallpaper images | 512 MiB |
avatars | Prepared avatar images | 512 MiB |
Original images are preserved. Missing, damaged, or outdated caches regenerate automatically, including after image replacements or renderer upgrades.
To clear rendered backgrounds:
rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/veila/backgrounds"Still stuck
Include these in a GitHub issue:
- Distro and compositor version
- Whether you use
veila idleorveila.service - Output of
veila doctor,veila check-config, andveila status - Relevant lock and watcher logs