pi-ext
bugabingas pi extensions
owned by bugabinga
docs: harden hypr troubleshooting guidance
25cef909dabcce09dc761bbc823b8793c2534146
Oliver Jan Krylow <oliver@bugabinga.net> ·
unsigned
Browse filesCompare with HEAD
Changed files (5)
skills/hypr/SKILL.md
Modified11 11 Config root is usually `~/.config/hypr/`.
12 12 Current + old dotfiles differ; detect installed version + config syntax before
14 +Broken/in-transition setups are normal.
16 17 ##
First response checklist 35 36 hyprctl activewindow
37 + hyprctl configerrors
41 + If `HYPRLAND_INSTANCE_SIGNATURE` is missing, derive it from `hyprctl
42 + instances` and retry with that env var.
39 44 4. Verify docs for installed version.
40 45 Official wiki targets current/-git; old configs may use old syntax.
41 46 5. Avoid X11 advice unless user explicitly asks about XWayland compatibility.
65 70 `references/config-basics.md`
66 71 - Hypr ecosystem tool configs:
67 72 `references/hypr-tools.md`
68 -- Troubleshooting portals, screenshare, input, rules, startup:
73 +- Broken configs, migrations, portals, input, rules, startup:
69 74 `references/troubleshooting.md`
70 75 - Dotfile/rice structure patterns:
71 76 `references/dotfiles-patterns.md`
skills/hypr/references/config-basics.md
Modified 18 18 legacy hyprlang config; still common in dotfiles.
19 19 - Split configs under `~/.config/hypr/conf/`, `hyprland/`, `custom/`, etc.
21 -Do not convert between syntax families unless asked.
21 +Hyprland 0.55+ docs emphasize Lua, but many working/broken setups still keep
22 +legacy `hyprland.conf`.
23 +Treat that as migration state.
24 +Do not convert or mix syntax families unless asked.
23 26 ##
Core config areas 144 147 ##
Rules that save time 149 +- Run `hyprctl configerrors` before adding features; fix parser errors first.
146 150 - Output names change; use `hyprctl monitors all` or `desc:` matching for stable
148 152 - Monitor positions use logical/scaled pixels; no overlap allowed.
skills/hypr/references/ecosystem-taxonomy.md
Modified 3 3 #
Hyprland ecosystem taxonomy 7 7 Prefer `hypr*` when first-party and sufficient.
8 +If user already chose a non-Hypr Wayland tool, preserve that choice unless it
9 +conflicts or is obsolete.
8 10 Use one primary per overlapping category.
10 12 ##
Compositor/session 21 23 | File picker portal | xdg-desktop-portal-gtk | xdg-desktop-portal-kde | XDPH does not own file picker |
22 24 | Audio/video graph | PipeWire + WirePlumber | distro-specific PipeWire launcher | required for screen share |
23 25 | Polkit auth | hyprpolkitagent | polkit-kde-agent, GNOME polkit agent | run one agent |
24 -| Notifications | swaync | mako, dunst, fnott | run one daemon; swaync also notification center |
26 +| Notifications | mako / swaync | dunst, fnott | run one daemon; swaync adds notification center |
26 28 ##
Hypr first-party user apps 69 71 ##
Screenshots/recording/screenshare 71 -| Role | Prefer/typical | Alternatives | Notes |
72 -| -------------- | ----------------------------- | --------------------- | ----------------------------- |
73 -| Screenshot raw | grim + slurp | HyprCapture, hyprshot | Wayland-native capture |
74 -| Annotate | satty | swappy | consumes screenshot pipe/file |
75 -| Clipboard | wl-copy/wl-paste | cliphist frontend | Wayland clipboard |
76 -| Recording | wf-recorder | wl-screenrec, OBS | OBS uses PipeWire/portal |
77 -| Screenshare | XDPH + PipeWire + WirePlumber | browser/app portal UI | portal config/logs matter |
73 +| Role | Prefer/typical | Alternatives | Notes |
74 +| -------------- | ----------------------------- | --------------------- | ------------------------------ |
75 +| Screenshot raw | grim + slurp | hyprshot, HyprCapture | Wayland-native capture |
76 +| Annotate | satty | swappy, Flameshot | Flameshot usually needs portal |
77 +| Clipboard | wl-copy/wl-paste | cliphist frontend | Wayland clipboard |
78 +| Recording | wf-recorder | wl-screenrec, OBS | OBS uses PipeWire/portal |
79 +| Screenshare | XDPH + PipeWire + WirePlumber | browser/app portal UI | portal config/logs matter |
79 81 Avoid `xclip`, `xsel`, X11 screenshot tools.
skills/hypr/references/troubleshooting.md
Modified16 17 journalctl --user -b | grep -Ei 'hypr|xdg-desktop-portal|pipewire|wireplumber|polkit'
20 +If `HYPRLAND_INSTANCE_SIGNATURE` is missing, derive it from `hyprctl instances`
21 +and rerun probes with that env var.
28 32 1. Identify syntax family (`hyprland.lua` vs legacy `hyprland.conf`).
29 -2. Check current/versioned wiki for that syntax.
30 -3. Bisect included config files or recent dotfile changes.
33 +2. If Hyprland is newer than config style, classify as migration state.
34 +3. Check current/versioned wiki for that syntax.
35 +4. Fix parse errors before feature work.
36 +5. Bisect included config files or recent dotfile changes.
32 38 copy original file or commit/stash before edits.
34 40 ##
Screenshare / portals skills/hypr/references/upstream.md
Modified12 12 hyprctl devices # keyboards, mice, switches, keymap device names
13 13 hyprctl binds # active binds + descriptions
14 14 hyprctl getoption <
option> # live option value
15 +hyprctl configerrors # current config errors
16 +hyprctl instances # running compositor instances
15 17 hyprctl reload # reload config
16 18 hyprctl reload full-reset # only for syntax-family reset when needed
17 19 hyprctl dispatch '...' # run dispatcher
18 20 hyprctl eval '...' # eval Lua/current config expression
23 +If Pi runs outside the Hyprland env and `hyprctl` says
24 +`HYPRLAND_INSTANCE_SIGNATURE not set`, use the instance list:
27 +sig=$(hyprctl instances | awk '/^instance /{sub(":", "", $2); print $2; exit}')
28 +HYPRLAND_INSTANCE_SIGNATURE="$sig" hyprctl version
31 +Use same env prefix for other `hyprctl` probes.
21 33 Use tool help for exact current CLI:
68 80 1. Run `hyprctl version`.
69 81 2. Look at user's config filename + syntax.
70 82 3. If current wiki syntax differs, use versioned wiki matching user's version.
71 -4. If dotfile uses legacy syntax, do not blindly paste current Lua snippets.
72 -5. Prefer live introspection (`hyprctl ...`) over stale examples.
83 +4. If installed Hyprland is current but config is legacy, treat as migration
84 + state; do not mix syntax without explicit migration.
85 +5. If dotfile uses legacy syntax, do not blindly paste current Lua snippets.
86 +6. Prefer live introspection (`hyprctl ...`) over stale examples.
74 88 ##
Research dotfiles safely