Frequently Asked Questions

Stasis Not Detecting Apps

If Stasis isn't detecting your applications for idle inhibition:

Ensure your compositor is supported (see Supported Compositors)
Halley, Niri, and Hyprland have native app tracking; labwc and River use process-based fallback detection
Start your compositor in a real session context (niri-session, dbus-run-session, or compositor-recommended launcher)
Check that the app names in inhibit_apps match the actual application names
For Halley, patterns match window app_id values from halleyctl node list --json
Use stasis -v or check ~/.local/state/stasis/stasis.log for detailed logs on detected apps

D-Bus Inhibits or Media Not Working

Browser and portal inhibit requests are handled by enable_dbus_inhibit, not by monitor_media. Audio playback and call detection use pactl through PulseAudio or PipeWire Pulse.

Keep enable_dbus_inhibit true for browser, Steam, and portal inhibit traffic
Start the compositor inside a real D-Bus session so session-bus monitoring is available
Install pulseaudio or pipewire-pulse so pactl is available
Use media_blacklist only for media sources you want to ignore

Web Discord limitation Browser/portal behavior can still drop inhibits during some web Discord calls when no microphone source-output is attached. This is a browser/portal signal limitation rather than a normal config error.

Lock Step Fires Repeatedly

If Stasis locks, immediately resumes, and starts the plan again, first check which completed-state signal your locker provides.

Foreground lockers are tracked until their process exits
Lockers such as Veila publish login1 LockedHint, which Stasis follows automatically
Remove fork/daemonize options such as swaylock -f if the locker does not publish LockedHint
Do not use loginctl lock-session as completion tracking; its lock/unlock signals are requests
Confirm the loop with recent logs:

stasis dump 200

Stasis 1.4.1 and newer: A positive LockedHint takes authority for the current lock episode, so a short-lived locker client can exit without producing a false unlock.

Regex Patterns Not Matching

If your regex patterns in inhibit_apps aren't working:

Ensure you're using raw string syntax: r"pattern"
Test patterns with verbose logging to see what apps are detected
Remember that process-based fallback detection may report different names than native compositor IPC

💡 Tip: Run Stasis with verbose logging (stasis -v) to see exactly what application names are being detected, then adjust your patterns accordingly.

Service Not Starting

If your systemd service won't start:

Verify the ExecStart path in your systemd service file points to the correct binary location
Check service logs for specific errors:

journalctl --user -u stasis.service

Common issues include incorrect binary paths or missing dependencies.

If Stasis starts but cannot see Wayland, D-Bus, or compositor-specific environment variables, ensure your user service receives WAYLAND_DISPLAY, XDG_RUNTIME_DIR, DBUS_SESSION_BUS_ADDRESS, and compositor variables such as NIRI_SOCKET when required.

Configuration Not Reloading

If changes to your configuration aren't taking effect:

Use stasis reload to send a reload signal to the running daemon
Check configuration syntax if reload fails
Restart the service if reload continues to fail:

systemctl --user restart stasis.service

Configuration Errors

If Stasis reports configuration errors:

Validate your RUNE syntax (see RUNE notes in documentation)
Verify built-in action block names:
- startup
- lock_screen / lock-screen
- dpms
- suspend
- brightness
- * (custom actions can be named anything)
Check the manual: man 5 stasis
Use verbose logging to identify configuration issues