Stasis
GitHub

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 blame to see which applications, media, D-Bus, or login1 idle holds are currently blocking idle
  • 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, portal inhibit traffic, and blocking login1 idle inhibitors
  • 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
  • Use suspend_inhibit_media when playback should still allow lock and DPMS, but not automatic suspend
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 and DPMS Run, but Suspend Waits

That can be intentional. Suspend-only holds block automatic sleep while earlier plan steps continue. They come from suspend_inhibit_apps, suspend_inhibit_media, or blocking login1 idle inhibitors discovered through enable_dbus_inhibit.

  • When the last matching hold clears, Stasis resumes the remaining suspend timeout
  • Manual stasis trigger suspend still runs immediately
  • Confirm the current blockers with:
stasis blame

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 upgrades preserve customized files and symlinks. Stasis renames only known legacy keys and backfills compatibility fields instead of replacing the entire file with the current bootstrap.

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

Need More Help?

If your problem isn't listed here and you've tried everything:

🐛 Open a Bug Report

Visit the GitHub Issues page to report your problem. Please include:

  • Your distribution and compositor
  • Stasis version (stasis --version)
  • Relevant log output from ~/.local/state/stasis/stasis.log
  • Your configuration file (sanitize any sensitive info)