marceloeatworld/hyprland-ai-skill
hyprland
FlaggedThis skill should be used when the user asks about "Hyprland configuration", "hyprland.lua", "hyprland.conf", "Hyprland Lua config", "hyprctl", "Hyprland keybinds", "Hyprland window rules", "Hyprland monitors", "Hyprland dispatchers", "Hyprland animations", "Hyprland workspaces", "Hyprland IPC", "Hyprland plugins", "hyprlock", "hypridle", "hyprpaper", "hyprcursor", "hyprpicker", "hyprsunset", "xdg-desktop-portal-hyprland", "Hyprland on NixOS", "Hyprland Home Manager", "Hyprland layouts", "Hyprland dwindle", "Hyprland master layout", "Hyprland FAQ", "Hyprland performance", "Hyprland Nvidia", "Hyprland screen sharing", "Hyprland special workspace", "Hyprland smart gaps", "Hyprland multi-monitor", "Hyprland tearing", or any topic related to configuring, troubleshooting, or extending the Hyprland Wayland compositor and its ecosystem tools.
references/crashes-and-bugs.md
View on GitHub<!-- source: https://wiki.hypr.land/crashes-and-bugs -->
<!-- wiki commit: 41c7222 (2026-11-20 18:16:21 +0100) -->
<!-- auto-generated by scripts/generate-references.sh - DO NOT EDIT MANUALLY -->
---
weight: 110
title: Crashes and Bugs
---
## Getting the log
First, make sure logging is enabled by [setting](../configuring/core/config-options#syntax) `debug.disable_logs` to `false`.
If you also need OpenGL messages, set `debug.gl_debugging` to `true`.
Remember to unset these when done logging, as they negatively impact performance.
> [!TIP]
> Debug logging can be toggled dynamically, using `hyprctl eval` to change the option at runtime.
> If you don't need to see startup logs, consider setting debug options this way (rather than in your config file), so that you can simply reload your config to disable logging when you finish.
If you are in a TTY, and the Hyprland session that crashed was the last one you launched, the log can be printed with
```sh
cat $XDG_RUNTIME_DIR/hypr/$(ls -t $XDG_RUNTIME_DIR/hypr/ | head -n 1)/hyprland.log
```
If you are in a Hyprland session, and you want the log of the last session, use
```sh
cat $XDG_RUNTIME_DIR/hypr/$(ls -t $XDG_RUNTIME_DIR/hypr/ | head -n 2 | tail -n 1)/hyprland.log
```
## Obtaining the Hyprland Crash Report
If you have `$XDG_CACHE_HOME` set, the crash report directory is `$XDG_CACHE_HOME/hyprland`.
If not, it's `$HOME/.cache/hyprland`.
Go to the crash report directory and you should find a file named `hyprlandCrashReport[XXXX].txt` where `[XXXX]` is the PID of the process that crashed.
Attach that file to your issue.
## Crashes at launch
Diagnose the issue by what is in the log:
- `backend failed to start`: launch in the TTY and refer to the logs shown in RED.
- `Monitor X has NO PREFERRED MODE, and an INVALID one was requested`: your monitor is broken.
- Other: see the coredump. Use `coredumpctl`, find the latest one's PID and do `coredumpctl info PID`.
- failing on a driver (e.g. `radeon`): report an issue.
- failing on `Hyprland`: report an issue.
## Crashes not at launch
Report an issue on GitHub or on the Discord server.
## Obtaining a debug stacktrace
> Systemd-only.
1. Build Hyprland in debug (`make debug`).
1. Start Hyprland and get it to crash.
1. In a TTY or terminal, do `coredumpctl debug Hyprland`.
- If GDB asks you for symbols, say `y`.
- If it asks about paging, say `c`.
1. Once you get to `(gdb)`, start file logging with `set logging enabled`.
- For a specific file, use `set logging file output.log`.
1. Run `bt -full`, then `exit` once finished, and attach the output.
## Obtaining a trace log
Launch Hyprland with `HYPRLAND_TRACE=1 AQ_TRACE=1` environment variables set.
These variables will enable _very_ verbose logging and it's not recommended to enable them unless debugging, as they might cause slowdowns and _massive_ log files.
Try to reproduce your issue as fast as possible so we don't have to sift through 1 million lines of logs.
## Bugs
First of all, **_READ THE [FAQ PAGE](../faq)_**.
If your bug is not listed there, you can ask on the Discord server or open a [discussion on GitHub](https://github.com/hyprwm/Hyprland/discussions).
## Bisecting an issue
"Bisecting" is finding the first _git_ commit that introduced a specific bug or regression using binary search.
This is done in `git` using the `git bisect` command.
First, clone the Hyprland repo if you haven't already:
```sh
git clone --recursive https://github.com/hyprwm/Hyprland
cd Hyprland
```
Start the bisect process:
```sh
git bisect start
```
Enter the first known good commit hash that did not contain the issue:
```sh
git bisect good [good commit]
```
Then, enter the known bad commit hash that does contain the issue. You can simply use HEAD:
```sh
git bisect bad HEAD
```
`git` will now checkout a commit in the middle of the specified range.
Now, reset and build Hyprland:
```sh
git reset --hard --recurse-submodules
make all
```
...and run the built executable from the TTY `./build/Hyprland`.
Try to reproduce your issue.
If you can't (i.e. the bug is not present), go back to the Hyprland repo and run `git bisect good`.
If you can reproduce it, run `git bisect bad`.
`git` will then checkout another commit and continue the binary search.
If there's a build error, run `git bisect skip`.
Reset, build and install Hyprland again and repeat this step until `git` identifies the commit that introduced the bug:
```
[commit hash] is the first bad commit
```
## Building the Wayland stack with ASan
If requested, this is the deepest level of memory issue debugging possible.
_Do this in the TTY, with no Hyprland instances running._
Clone Hyprland: `git clone --recursive https://github.com/hyprwm/Hyprland`
`make asan`
Reproduce your crash.
Hyprland will exit back to the TTY.
Now, in either `cwd`, `~` or `./build`, search for file(s) named `asan.log.XXXXX` where XXXXX is a number.
Zip all of them up and attach to your issue.
## Debugging DRM issues
DRM (Direct Rendering Manager) is the underlying kernel architecture to take a GPU buffer (something we can render to) and put it on your screen (via the GPU) instead of a window.
Freezes, glitches, and others, can be caused by issues with Hyprland's communication with DRM, the driver or kernel.
In those cases, a DRM log is helpful.
> [!WARNING]
> Please note, these logs are EXTREMELY verbose.
> Please reproduce your bug(s) ASAP to avoid getting a 1GB log.
```sh
echo 0x19F | sudo tee /sys/module/drm/parameters/debug # enables verbose drm logging
sudo dmesg -C # clears kernel debug logs
dmesg -w > ~/dmesg.log & # writes kernel logs in the background to a file at ~/dmesg.log
Hyprland
# ... repro the issue, then quit Hyprland
fg # after this, use CTRL+C to stop writing the logs
echo 0 | sudo tee /sys/module/drm/parameters/debug # disables drm logging, don't forget this to avoid slowdowns
```
After this, _attach_ the `dmesg.log` file.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |