Troubleshooting

Startup fails

Run the local diagnostic report first:

veila doctor

It checks the current Wayland session environment, ext-session-lock-v1 compositor support, renderer protocol support, estimated renderer memory budgets, logind session resolution, config loading, bundled themes, the PAM service file, whether veilad is reachable, the veila-idle.service state, and optional ~/.config/veila/idle.env values.

To check the installed Veila version:

veila -v

If you only need to check config files, use:

veila check-config

If the user service veilad.service exits, first inspect the logs:

veila logs --lines=80

For the idle and sleep monitor service:

veila logs --idle --lines=80

Common cause:

• Veila could not resolve the correct logind session for the service context

If you are on Hyprland, exec-once = veilad is still the simpler startup path.

Service does not lock

If veila lock works from a terminal but the user service does not, the interactive shell and systemd --user service are usually starting with different session context.

Useful checks:

echo "$XDG_SESSION_ID"
systemctl --user show-environment | rg 'XDG_SESSION_ID|XDG_SESSION_TYPE|WAYLAND_DISPLAY|HYPRLAND'

If the interactive shell path is reliable for you, prefer:

exec-once = veilad

Live logs

For live manual debugging:

pkill -x veilad
RUST_LOG=debug veilad

Then from another terminal:

veila lock

For a user service:

veila logs --follow

For the idle monitor service:

veila logs --idle --follow

Useful filters:

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

Lock before sleep

If a script must wait for the secure lock to become active before continuing, use:

veila lock --wait-ready && systemctl suspend

This is the recommended form for Hypridle before_sleep_cmd, DPMS chains, and other automated lock hooks. Plain veila lock is still fine for manual keybinds.

lock_ready=true means the daemon has already received curtain readiness from the secure session-lock path. If the daemon was already locked, Veila also prints:

already_active=true

Emergency prompt test

If you need to verify that Veila can still unlock when rich rendering is unavailable, force the built-in emergency prompt:

veila lock --force-emergency-ui --wait-ready

This should show a minimal password field on the secure lock surfaces. Authentication still goes through the normal daemon and PAM flow.

Activation latency

To see where lock startup time is going:

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

The report is useful for checking whether delay comes from daemon setup, spawning veila-curtain, Wayland startup, surface configure, first frame rendering, or compositor session-lock confirmation.

For microsecond precision while profiling locally:

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

Verbose output also includes derived gaps between first frame, all configured surfaces, and compositor session-lock confirmation.

Persistent logs

veila logs reads the systemd user journal by default. If you start the daemon with exec-once = veilad instead of a user service, use config-based file logging:

[lock]
log_to_file = true
log_file_path = "~/.local/state/veila/veilad.log"

Then inspect it with:

veila logs --file
veila logs --file --follow
veila logs --file --lines=100

Slow activation

The biggest real latency factors are usually large blurred layers, high blur_strength, multi-monitor setups, mixed-resolution outputs like 4K + 4K + 2K.

veila doctor prints renderer estimates such as renderer.ready_estimated_kib, renderer.post_ready_estimated_kib, renderer.shm_one_slot_estimated_kib, and renderer.shm_two_slot_estimated_kib. These are planning estimates for the current outputs and config; live debug logs from veilad remain the source of truth for exact curtain RSS during a lock.

If you want a faster path, try smaller layer width or height, lower blur_strength, mode = "solid" instead of mode = "blur"

Veila stores rendered background cache files under ${XDG_CACHE_HOME:-~/.cache}/veila/backgrounds. The daemon periodically prunes old rendered cache entries and keeps the rendered cache below its built-in size limit. For one-off troubleshooting, you can remove the rendered cache manually:

rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/veila/backgrounds"

Still stuck

When reporting an issue, include:

• distro
• compositor
• whether you use exec-once = veilad or veilad.service
• output of veila doctor
• output of veila check-config
• output of veila status
• relevant daemon logs

Open an issue on GitHub with the above details.