---
description: >-
  Override the package-managed hyprland.desktop with a local copy that points
  to start-hyprland (watchdog binary), ensuring Hyprland launches with proper
  crash diagnostics, signal handling, and XDG portal support via uwsm.
status: accepted
date: 2026-05-21
---

# 0004: start-hyprland Watchdog Override

## Context

Hyprland 0.53+ ships `start-hyprland`, a watchdog binary that monitors the
compositor process, collects crash diagnostics (crash reports, memory dumps),
and ensures proper signal handling. When Hyprland detects it was not launched
via `start-hyprland`, it displays a banner warning:

> `⚠ Hyprland was started without start-hyprland. This is highly not
> recommended unless you are in a debugging environment.`

Our setup uses: greetd → tuigreet → `uwsm start -e -D Hyprland hyprland.desktop`

uwsm reads the `.desktop` file's `Exec=` field and spawns that binary inside
a systemd user session. The package-provided `hyprland.desktop` has
`Exec=Hyprland` (direct binary), bypassing the watchdog.

### Research (Dec 2025 – Jan 2026)

- Hyprland discussion #12661: widespread report of this warning with UWSM.
- UWSM maintainer Vladimir-csp confirmed: "I'd recommend feeding
  `hyprland.desktop` to uwsm" with the watchdog binary.
- fufexan (Hyprland maintainer) acknowledged the incompatibility; no upstream
  fix landed as of Jan 2026.
- Community consensus: point `.desktop` Exec to `start-hyprland` via local
  override to preserve uwsm session management while enabling the watchdog.

## Decision

Create a local override at `~/.local/share/wayland-sessions/hyprland.desktop`
pointing to `start-hyprland`.

### Why local override (not system-wide)?

- The system file (`/usr/share/wayland-sessions/hyprland.desktop`) is owned by
  the `hyprland` package and gets overwritten on updates.
- `~/.local/share` has higher XDG_DATA_DIRS priority than `/usr/share`, so
  greetd/tuigreet discover the override first without touching system files.
- Ansible manages the override idempotently.

### Why not modify greetd's command?

The greetd command (`uwsm start -e -D Hyprland hyprland.desktop`) references
`hyprland.desktop` generically. Changing the greeting command to
`start-hyprland` directly would bypass uwsm entirely. The override approach
keeps the uwsm session management intact while fixing the watchdog issue.

## Status

Implemented in Ansible role `hyprland/tasks/main.yml`:
- Task registers the override at `~/.local/share/wayland-sessions/hyprland.desktop`
- Uses `start-hyprland` as `Exec` and `TryExec`
- Sets correct ownership (`mw`) and permissions (`0644`)
- Tagged `[hyprland, session]` for idempotent runs

## Verification

After running `ansible-playbook ansible/workstation.yml`:
1. `cat ~/.local/share/wayland-sessions/hyprland.desktop` should show
   `Exec=start-hyprland`
2. Next login: the warning banner should no longer appear.
3. `ps aux | grep start-hyprland` should show the watchdog parent process.