Troubleshooting

Troubleshooting

Panel fails to open

• Confirm the session type is Wayland: echo $XDG_SESSION_TYPE.
• Confirm GTK4 + gtk4-layer-shell are installed.
• Confirm the compositor allows layer-shell surfaces.
• Run noticenterctl open-panel --debug info and review logs.

Popups missing or delayed

• Confirm the daemon is running: systemctl --user status unixnotis-daemon.
• Verify popups.output matches the compositor output name when set.
• Ensure inhibit.mode is not set to drop_all.

Icons missing

• Confirm icon themes are installed (hicolor is required).
• Confirm notification image hints contain valid paths.
• Validate CSS changes with noticenterctl css-check if custom themes are used; warnings often indicate intentional overrides but are useful to catch accidental duplicates.

Widgets not updating

• Confirm required external commands are installed for the widget.
• Prefer watch_cmd for event-driven widgets to reduce polling.
• Review refresh_interval_ms and refresh_interval_slow_ms under [widgets].

Installer permission errors

• Confirm $HOME/.local/bin is writable.
• Remove root-owned files created by a previous install.

Restore config after a bad edit

• Run the installer and choose Reset config → Restore backup.
• Backups live under $XDG_CONFIG_HOME/unixnotis/Backup-YYYY-MM-DD.
• Fallback backup path: $HOME/.config/unixnotis/Backup-YYYY-MM-DD.
• Retention is controlled in $XDG_CONFIG_HOME/unixnotis/installer.toml.