# 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.