# How to Report a Bug in Hyprland: A Complete Guide with Logs and Crash Reports

> Effectively report Hyprland bugs. Learn to gather logs, attach config files, and include crash reports to help developers resolve issues faster. Find out how to report bugs in Hyprland today.

- Repository: [Hypr Development/Hyprland](https://github.com/hyprwm/Hyprland)
- Tags: how-to-guide
- Published: 2026-07-29

---

**To report a bug in Hyprland effectively, search existing issues first, then gather your runtime logs from `$XDG_RUNTIME_DIR/hypr`, attach your configuration file, and include crash reports from `$XDG_CACHE_HOME/hyprland` if the compositor segfaults.**

The Hyprland repository provides a structured workflow and built-in diagnostics via the `CLogger` class to help users report bugs comprehensively. Understanding how to collect these artefacts—runtime logs, configuration files, and crash reports—ensures developers can reproduce and fix issues efficiently. This guide covers the exact steps to gather diagnostic data from the source code, including file paths and commands extracted from [`src/debug/log/Logger.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/debug/log/Logger.cpp).

## Verify the Issue Is Unique

Before filing a new report, confirm the bug hasn't been documented already. Check the [FAQ](https://wiki.hypr.land/FAQ/) and [Configuring documentation](https://wiki.hypr.land/Configuring/) to rule out misconfiguration. Search the [GitHub issue tracker](https://github.com/hyprwm/Hyprland/issues) for similar symptoms to avoid duplicates.

## Document Reproduction Steps

Write a clear **Steps to reproduce** section that describes exactly how to trigger the bug. Include the **Expected outcome** and **Observed outcome** to clarify the discrepancy. If Hyprland does not crash, this documentation combined with your configuration and log files is sufficient for investigation.

## Gather the Hyprland Runtime Log

The compositor writes runtime diagnostics via the `CLogger` class, implemented in [`src/debug/log/Logger.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/debug/log/Logger.cpp). The logger selects the output file based on the build type:

```cpp
// Inside CLogger::initIS
m_logger.setOutputFile(std::string{IS} + (ISDEBUG ? "/hyprlandd.log" : "/hyprland.log"));

```

Logs are stored under `$XDG_RUNTIME_DIR/hypr/` in session-specific subdirectories.

### Retrieve Logs from a TTY

If you are in a TTY and the crashed session was the most recent one launched:

```bash
cat $XDG_RUNTIME_DIR/hypr/$(ls -t $XDG_RUNTIME_DIR/hypr | head -n 1)/hyprland.log

```

### Retrieve Logs from a Running Session

If you are inside a running Hyprland instance and need the previous session's log:

```bash
cat $XDG_RUNTIME_DIR/hypr/$(ls -t $XDG_RUNTIME_DIR/hypr | head -n 2 | tail -n 1)/hyprland.log

```

The directories under `$XDG_RUNTIME_DIR/hypr` correspond to individual sessions, where the most recent entry (`head -n 1`) represents the active session.

## Attach Your Configuration

Include your complete [`hyprland.conf`](https://github.com/hyprwm/Hyprland/blob/main/hyprland.conf) or [`hyprland.lua`](https://github.com/hyprwm/Hyprland/blob/main/hyprland.lua) file in the bug report. The compositor loads this configuration at startup, and developers need it to reproduce your exact environment.

## Provide Crash Reports (v0.22.0β and newer)

When Hyprland crashes, it writes a crash report file to your cache directory. Check `$XDG_CACHE_HOME/hyprland` if the variable is set; otherwise, look in `$HOME/.cache/hyprland`.

The file follows the naming pattern `hyprlandCrashReport[PID].txt`. To locate recent reports:

```bash
cache_dir=${XDG_CACHE_HOME:-$HOME/.cache}/hyprland
ls -t "$cache_dir"/hyprlandCrashReport*.txt | head -n 5

```

Attach the newest file to your GitHub issue.

## Provide Core Dumps (v0.21.0β and older)

For older versions or when crash reports are unavailable, retrieve the core dump via `systemd`:

```bash
coredumpctl               # List entries to find the Hyprland PID

coredumpctl info <PID>    # Replace <PID> with the actual process ID

```

Include the stack trace output from `coredumpctl info` in your report.

## Enable Debug Builds for Verbose Logging (Optional)

For maximum diagnostic detail, build Hyprland in debug mode and run it with AddressSanitizer:

1. Compile Hyprland with debug symbols enabled.
2. Launch with `ASAN_OPTIONS="log_path=asan.log"` to generate AddressSanitizer logs.
3. Attach the resulting `asan.log.<PID>` file to your issue.

You can also enable verbose runtime logging without rebuilding by adding these lines to your configuration:

```ini
debug:disable_logs=0
debug:enable_stdout_logs=1
debug:colored_stdout_logs=1
debug:disable_time=0

```

These options are processed by `CLogger::recheckCfg()` in [`src/debug/log/Logger.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/debug/log/Logger.cpp), controlling file output, stdout verbosity, colorization, and timestamps.

## Submit the Issue

Create your report at [https://github.com/hyprwm/Hyprland/issues](https://github.com/hyprwm/Hyprland/issues). Populate all sections of the issue template, attach the gathered logs and configuration, and provide the crash report or core dump if applicable.

## Summary

- Search existing issues and the FAQ before reporting to avoid duplicates.
- Retrieve logs from `$XDG_RUNTIME_DIR/hypr/` using session directory sorting commands.
- Attach your full [`hyprland.conf`](https://github.com/hyprwm/Hyprland/blob/main/hyprland.conf) or [`hyprland.lua`](https://github.com/hyprwm/Hyprland/blob/main/hyprland.lua) configuration file.
- Include crash reports from `$XDG_CACHE_HOME/hyprland` for versions v0.22.0β and newer.
- Use `coredumpctl` for stack traces on v0.21.0β and older systems.
- Enable debug logging via configuration options processed by `CLogger::recheckCfg()`.

## Frequently Asked Questions

### Where does Hyprland store its runtime logs?

Hyprland stores runtime logs in `$XDG_RUNTIME_DIR/hypr/` under session-specific subdirectories, with filenames determined by the build type (`hyprland.log` for release, `hyprlandd.log` for debug). The `CLogger` class in [`src/debug/log/Logger.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/debug/log/Logger.cpp) handles the path construction by appending the filename to the runtime instance directory.

### What should I do if Hyprland crashes but I cannot find a crash report?

If you are running version v0.21.0β or older, or if the crash report is missing, use `coredumpctl` to extract the core dump and stack trace from `systemd`. For newer versions, ensure you check both `$XDG_CACHE_HOME/hyprland` and `$HOME/.cache/hyprland` for files named `hyprlandCrashReport[PID].txt`.

### How do I get the previous session's log while currently running Hyprland?

Use the command `cat $XDG_RUNTIME_DIR/hypr/$(ls -t $XDG_RUNTIME_DIR/hypr | head -n 2 | tail -n 1)/hyprland.log` to access the second most recent session directory, which contains the previous session's log file.

### Is a debug build necessary for reporting bugs?

No, a debug build is optional but recommended for complex issues. You can provide sufficient information using release builds by attaching the standard log, configuration, and crash reports. Debug builds with `ASAN_OPTIONS` provide additional AddressSanitizer logs that help diagnose memory-related crashes.