hyprland-debug

Diagnose Hyprland/Wayland issues by parsing logs and validating state.

3|Updated Jul 17, 2024
One-click install
npx skills add https://github.com/Castrozan/.dotfiles --skill hyprland-debug
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: hyprland-debug
Source: https://github.com/Castrozan/.dotfiles/tree/main/agents/skills/hyprland-debug
Command: npx skills add https://github.com/Castrozan/.dotfiles --skill hyprland-debug

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Diagnosing Hyprland/Wayland issues.

Core Features & Use Cases

  • Centralized log analysis: aggregates Hyprland logs from /run/user/$(id -u)/hypr/*/hyprland.log and surfaces common failure signals.
  • Deterministic checks: validates HYPRLAND_INSTANCE_SIGNATURE and ensures state consistency to avoid stale sessions.
  • Use Case: When theme switching fails, windows disappear, services crash, or displays malfunction, it identifies root causes and suggests fixes.

Quick Start

Use the hyprland-debug skill to diagnose current Hyprland issues and surface actionable fixes.

Frequently Asked Questions about hyprland-debug

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I diagnose Hyprland issues when windows disappear or displays malfunction?

Diagnosing Hyprland issues involves aggregating logs from /run/user/$(id -u)/hypr/*/hyprland.log and verifying state via HYPRLAND_INSTANCE_SIGNATURE to identify root causes for disappearing windows or malfunctioning displays.

Why does my Wayland theme switching fail and how can I find the root cause?

Wayland theme switching fails due to state inconsistencies or crashing user services. You can find the root cause by parsing Hyprland logs and verifying your HYPRLAND_INSTANCE_SIGNATURE to avoid stale sessions.

Can I use systemd to debug Hyprland services when they crash?

Yes, you can debug Hyprland services by parsing systemd user service logs alongside Hyprland's internal logs. This process verifies the active HYPRLAND_INSTANCE_SIGNATURE and checks for failure signals to surface actionable fixes.

Does NixOS require special steps to troubleshoot Hyprland log errors?

Troubleshooting Hyprland log errors on NixOS requires accessing logs located at /run/user/$(id -u)/hypr/*/hyprland.log. You must validate the HYPRLAND_INSTANCE_SIGNATURE to ensure state consistency before applying fixes.

What's the best way to identify stale Hyprland sessions causing display malfunctions?

The best way to identify stale Hyprland sessions causing display malfunctions is to run deterministic checks that validate the HYPRLAND_INSTANCE_SIGNATURE against your current user services and parse the active instance logs.

What should I do if hyprctl reports state inconsistencies during a Wayland session?

If hyprctl reports state inconsistencies during a Wayland session, you should aggregate logs from /run/user/$(id -u)/hypr/*/hyprland.log to surface failure signals and verify your HYPRLAND_INSTANCE_SIGNATURE.