3.5 KiB
When something breaks
Start here
Run Check System Health from the launcher, or open System Health. It reports what is actually running rather than what was installed, and it can repair several things itself.
From a terminal, the same check is panama doctor.
The shell is gone
If the bar and dock disappear, the Quickshell process died. Restart Desktop
Shell from the launcher brings it back. If the launcher is also gone, press
Super + Shift + R for the fallback launcher, which depends on nothing but
itself and exists for exactly this.
From a terminal: qs -d starts the shell again.
A shortcut stopped working
Check Super + / first: if the shortcut shows a different chord than you
expect, something rebound it. The Keyboard page, under Input in Settings, can
reset any bind, or all of them at once.
If the whole keymap is missing from that list, the compositor config failed
to load. Hyprland --verify-config says why without touching your session.
The screen resolution is wrong
Settings has a Displays page. It opens on a picture of what is connected —
one display or several — and everything under that picture belongs to
whichever one you have selected. Every change there reverts itself after
fifteen seconds unless you confirm it, so a mode your monitor cannot show
cannot strand you, and that covers color, bit depth and mirroring as well as
resolution, scale and rotation. If you are already stranded, hyprctl monitors from a terminal shows what is applied.
Something asked for a password and I do not know why
Panama's password prompt names the action that asked. If it was started by an
agent or a script through panama-sudo, it also shows a stated reason,
labelled as an unverified claim, beside the real action.
If you did not expect it at all, cancel. Nothing that needs privileges is harmed by being refused.
A button did nothing except change its wording
That is the button working. Anything in Settings that removes something takes two presses: the first arms it, and the row then shows what is about to happen beside a Keep that backs out. The second press is the one that does it.
Only one button in Settings is armed at a time, so arming a second one disarms the first, wherever it was.
The network I need is not in the list
The Wi-Fi list is what is in range. Saved networks, further down Connections, is what this machine remembers, including the ones nowhere near you — which is where to tidy up a profile you want rid of, rather than waiting until you are standing next to it again. A network that broadcasts no name is joined with Join a hidden network…, at the bottom of the list.
Opening a connection shows what it actually got — address, gateway, DNS — and is where you give it a fixed address instead when what it got does not work, or mark it metered so updates and large downloads wait until you are somewhere else.
After an update, something is not right
panama migrate applies repairs this machine has not had yet. It is safe to
run at any time and does nothing when there is nothing to do.
If an update went badly, Snapshots under System can roll the system back. That tab is only there where btrfs snapshots are configured, so if you cannot see it, this machine has none to roll back to.
Reporting it
panama doctor produces a redacted summary suitable for pasting into an
issue. It deliberately omits tokens, hostnames and account details.