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.

Panel looks too large on laptop screens

• panel.width is now treated as a requested width and may be capped by monitor size at runtime.
• Very small widths can also hit the panel runtime floor. noticenterctl css-check now warns when [panel].width is below that floor because the center clamps it and the result can look like CSS or config edits were ignored.
• panel.width also does not override GTK natural width. If widgets need more horizontal space, the live panel can stay wider than the requested width.
• The most common width drivers are:
  • 4-column toggle rows
  • 2-column stat rows
  • 2-column card rows
  • theme rules with large min-width, padding, or margins
• The media row is now clamped to the panel body width, so if width still looks wrong after a reload, check toggle/stat/card sizing and theme CSS first.
• If lowering panel.width appears to do nothing, inspect widget CSS before assuming config reload is broken.
• For tighter layouts, reduce [panel].width and adjust [panel.margin].
• For tighter widget-driven layouts, reduce horizontal sizing in widgets.css and then retest panel.width.
• For side anchors, respect_work_area = true keeps the panel from overlapping reserved bars.

Panel height keeps changing

• [panel].height is now a percentage of usable monitor height, not a pixel value.
• Small values such as 1, 5, or 20 mean 1%, 5%, or 20% of usable height.
• Visible widgets, media, and the panel header still keep a minimum natural height.
• That means small percentage values can look almost identical until the requested height grows past the current content floor.
• If the panel looks correct after collapsing widgets, the widget stack is setting that floor.
• Widget min_height values and theme CSS padding are the first things to check.
• If a truly exact pixel height is needed, use [panel].height_override.
• height_override takes priority over height whenever it is set.
• height_override is still bounded by the visible content minimum. It does not clip controls.

Theme edits do not seem to apply

• Run noticenterctl css-check and read the active theme files section first.
• The live UI follows the active paths from [theme].base_css, [theme].panel_css, [theme].popup_css, [theme].widgets_css, and [theme].media_css.
• Start with the css-check summary line so it is clear whether the theme is fully clean, warning-only, or failed.
• Read grouped errors and warnings by file instead of scanning for single log lines.
• Lint warnings now include line and column information when the source location is reliable, which makes duplicate selectors, duplicate properties, and GTK-incompatible layout values faster to fix.
• Valid newer GTK CSS such as supported var(...) and calc(...) usage should now stay quiet, so repeated warnings usually mean a real layout or parser issue instead of the checker lagging behind the runtime.
• Extra .css files under the config tree that are not referenced by config.toml are now reported in notes.
• Missing theme targets and multiple theme slots pointing at the same file are also reported.
• Absolute paths and non-.css file names are allowed, but they make it easier to edit the wrong file by accident.
• Terminal runs use color for errors, warnings, notes, and final results. Redirected output stays plain text.

Shared preset import fails

• Run noticenterctl preset inspect <bundle.unixnotis> first.
• Then run noticenterctl preset import <bundle.unixnotis> --dry-run to view the write plan.
• If import is blocked, read the path in the error carefully. Import now rejects:
  • theme paths outside the UnixNotis config root
  • explicit command paths outside the UnixNotis config root
  • archive path traversal
  • symlink escape paths
• If import warns that the preset contains executable commands or bundled scripts:
  • choose Inspect executable content now? to open the review pager
  • inspect the runnable config slots and bundled script text
  • quit the pager with q
  • only continue when the source is trusted
• Non-interactive imports fail on executable content unless --allow-exec is passed.
• If import warns about CSS asset references, decide whether the shared theme is meant to depend on files outside the UnixNotis config root or on remote URLs before continuing.
• Real imports run noticenterctl css-check afterwards, so a successful import can still end with a CSS validation failure if the shared theme itself is broken.

Shared preset export fails

• Confirm config.toml exists under the UnixNotis config root.
• If export warns about host-specific command paths, let noticenterctl rewrite them in the bundled config.toml unless the preset is intentionally machine-local.
• If export warns about outside CSS asset references, check whether the theme depends on images outside $XDG_CONFIG_HOME/unixnotis.
• --except paths are relative to the UnixNotis config root. Good examples:
  • installer.toml
  • widgets.css
  • assets/bg.png
• config.toml cannot be excluded because the bundle would not be importable.

Media card does not show the expected labels

• [media].show_source controls the source badge row above the title.
• [media].show_source_when_single_player can hide that badge on single-player setups.
• [media].show_position controls the player counter pill.
• [media].show_position_when_single_player can keep the counter visible even when only one player exists.
• [media].show_title and [media].show_artist can hide those lanes without disabling the card.
• [media].title_fallback controls what appears when a player exposes no title.
• [media].source_aliases can rewrite noisy player names into stable labels for theming.
• Media-specific ricing belongs in [theme].media_css; editing only widgets.css can miss the active media layer.

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.
• Popup file-backed icons are normalized to the popup icon target size; oversized source files should no longer render giant icons.
• Very large raster sources are rejected before full decode, so broken or unusually large PNG/WebP/JPEG artwork may fail closed instead of spiking memory during popup rendering.
• Validate CSS changes with noticenterctl css-check if custom themes are used; warnings often indicate intentional overrides but are useful to catch accidental duplicates, theme path mistakes, and GTK-incompatible layout values.

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.