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

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.

Verify the Issue Is Unique

Before filing a new report, confirm the bug hasn't been documented already. Check the FAQ and Configuring documentation to rule out misconfiguration. Search the GitHub issue tracker 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. The logger selects the output file based on the build type:

// 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:

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:

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 or 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:

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:

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:

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, controlling file output, stdout verbosity, colorization, and timestamps.

Submit the Issue

Create your report at 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 or 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}