115 lines
4.6 KiB
Markdown
115 lines
4.6 KiB
Markdown
# Troubleshooting
|
|
|
|
## Status and logs
|
|
|
|
```bash
|
|
systemctl --user status revive-monitor-drm-watch.service
|
|
journalctl --user -u revive-monitor-drm-watch.service -b -f
|
|
```
|
|
|
|
Both scripts write to stderr; systemd captures their messages in the unit journal.
|
|
Direct manual runs write to the terminal. There is no separate logger/syslog tag.
|
|
|
|
## Missing Hyprland instance / IPC failure
|
|
|
|
From a Hyprland terminal, run `./scripts/install.sh --start` and add the startup
|
|
hook from README so each new login updates `HYPRLAND_INSTANCE_SIGNATURE`.
|
|
`hyprctl monitors` must list the output configured in `config.env`. A stale
|
|
signature, failed IPC call or absent output aborts recovery without switching VTs.
|
|
|
|
## No recovery after switching inputs
|
|
|
|
Observe events without starting another watcher:
|
|
|
|
```bash
|
|
udevadm monitor --kernel --property --subsystem-match=drm
|
|
```
|
|
|
|
Look for `HOTPLUG=1`. Then inspect the session:
|
|
|
|
```bash
|
|
loginctl list-sessions
|
|
loginctl show-session SESSION_ID -p User -p Type -p Active -p Seat -p VTNr -p Desktop
|
|
```
|
|
|
|
Expected: your numeric UID, `Type=wayland`, `Active=yes`, `Seat=seat0`, a VT from
|
|
1 to 63, and either a Hyprland desktop or an empty Desktop property. The helper
|
|
also checks these properties when invoked manually.
|
|
|
|
## Hyprland refresh failed / Lua syntax error
|
|
|
|
Version 0.2.0 sent legacy dispatch commands even to Lua-configured sessions.
|
|
On Hyprland 0.56.2 this produced `')' expected near 'on'` and aborted recovery
|
|
before the VT switch. Update to 0.2.1 with `./scripts/install.sh --start`.
|
|
|
|
The helper now reads `hyprctl -j status` to choose the active config provider.
|
|
For Lua it sends `hl.dsp.dpms({ action = "on", monitor = "HDMI-A-2" })` and
|
|
`hl.dsp.focus({ monitor = "HDMI-A-2" })` through `hyprctl dispatch`. The configured
|
|
output replaces `HDMI-A-2`. Legacy hyprlang and older versions remain supported.
|
|
See the official [hyprctl documentation](https://wiki.hypr.land/configuring/core/advanced-configuration/using-hyprctl/)
|
|
and [dispatchers](https://wiki.hypr.land/configuring/core/dispatchers/).
|
|
|
|
The journal identifies `DPMS` or `focus`, the command's exit status and its error
|
|
response. A zero exit status with an error response is also treated as failure.
|
|
|
|
## Invalid runtime directory
|
|
|
|
`XDG_RUNTIME_DIR` must be your login-managed, user-owned directory with mode 0700
|
|
(normally `/run/user/UID`). Do not set it to `/tmp` or run the service with sudo.
|
|
The systemd unit sets it from `%t`.
|
|
|
|
## sudo / VT return failures
|
|
|
|
Use `visudo` to verify the explicit VT permissions. Check authorization without
|
|
switching the display (replace the VTs to match your session):
|
|
|
|
```bash
|
|
sudo -n -l /usr/bin/chvt 2
|
|
sudo -n -l /usr/bin/chvt 1
|
|
```
|
|
|
|
A denied return permission aborts before the outward switch. Actual chvt errors
|
|
are still possible; a return failure is retried once and logged. A failed emergency
|
|
return requires manually returning to the graphical VT, e.g. Ctrl+Alt+F1 for VT1.
|
|
|
|
## Debounce hides a rapid return / repeated recoveries
|
|
|
|
`DEBOUNCE_SECONDS` is a cooldown after each attempt, not an event queue. A genuine
|
|
rapid return can be ignored along with duplicate and self-generated events.
|
|
Reduce the interval if needed; increasing it can help noisy hardware. Setting it
|
|
to zero disables cooldown and can cause a recovery loop on some GPUs.
|
|
|
|
## Manual recovery
|
|
|
|
From a terminal inside the active Hyprland session, pass its actual VT number:
|
|
|
|
```bash
|
|
~/.local/bin/revive-monitor-fix 1
|
|
```
|
|
|
|
This will visibly switch VTs. If the monitor needs more handshake time, increase
|
|
`HDMI_SETTLE_SECONDS` (default 5). Manual recovery still needs valid IPC, the
|
|
configured output, a private runtime directory and sudo permission.
|
|
|
|
## Updating / uninstalling
|
|
|
|
Updates preserve `config.env`. Run `./scripts/install.sh --start` inside Hyprland
|
|
to restart with the new scripts. Plain `install.sh` leaves the service stopped.
|
|
For uninstall, the systemd user manager must be reachable. Remove the startup
|
|
hook manually as documented in README.
|
|
|
|
## Hardware acceptance
|
|
|
|
The operator confirmed successful physical HDMI input switching and recovery
|
|
with version 0.2.1 on 2026-09-23. The tested setup and the scope of that result
|
|
are recorded in [hardware validation](hardware-validation.md).
|
|
|
|
After installation, check a normal input change, a rapid away/back change and a
|
|
logout/login cycle. Before Hyprland login there must be no chvt invocation from
|
|
this service. Automated tests use mocks and do not replace this hardware check.
|
|
|
|
For a first normal input-switch test with the default timing, stay on the other
|
|
input for about 40 seconds before returning. This allows the initial attempt
|
|
and its 30-second cooldown to finish. Then test rapid switching separately;
|
|
returns inside the cooldown can still be suppressed.
|