Skip to Content
Veila
Configuration

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 doctor

This 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 -v
veila check-config

If the watcher exits, inspect its journal:

veila logs --journal --idle --lines=80

A 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_restart unset, 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_restore before recovery tests. veila doctor reports 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 = veilad with exec-once = veila idle.

  • Remove the old service enablement link and enable the current unit. veila doctor prints the exact link path:

    rm ~/.config/systemd/user/graphical-session.target.wants/veilad.service
    systemctl --user enable veila.service

    systemctl --user disable veilad.service cannot remove that old link because the unit is now an alias.

  • Replace removed veilad --lock-now, --status, and --reload-config flags with veila lock, veila status, and veila reload.

  • File logs default to ~/.local/state/veila/veila.log; log_file_path overrides 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-pager

Alternatively, launch the watcher in your compositor session:

exec-once = veila idle

Live logs

Run a foreground lock with debug logging, then authenticate to finish:

RUST_LOG=debug veila lock

For the watcher journal:

veila logs --journal --idle --follow

Useful filters:

veila logs --since=10m
veila logs --curtain
veila logs --idle
veila logs --ui
veila logs --all

By 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 suspend

lock_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=true

Fingerprint 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-ready

Activation latency

Show startup, rendering, and lock-confirmation timings:

veila lock --latency-report --wait-ready

Add microsecond precision and gaps between stages:

veila lock --latency-report=verbose --wait-ready

Persistent 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=100

Slow 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 directoryContentsSize budget
backgroundsRendered backgrounds and panels768 MiB
source-imagesDecoded wallpaper images512 MiB
avatarsPrepared avatar images512 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 idle or veila.service
  • Output of veila doctor, veila check-config, and veila status
  • Relevant lock and watcher logs

On this page