How to Troubleshoot Omarchy Issues: A Complete Diagnostic Guide

Use omarchy-debug to generate system diagnostics at /tmp/omarchy-debug.log, restore default settings with omarchy-reinstall, and restart individual subsystems using omarchy restart-{service} commands when specific hardware stops responding.

Omarchy is a shell-based desktop environment developed by Basecamp that combines Hyprland, Quickshell plugins, and Lua configuration files to create a cohesive tiling window manager experience. When you need to troubleshoot Omarchy issues, the system provides first-party diagnostic tools and well-defined configuration paths that enable rapid recovery without full reinstallation. This guide covers the essential commands and file locations defined in the basecamp/omarchy source code to resolve common failure modes.

Common Omarchy Issues and Solutions

Recovering From System Breakage After Updates

If your system becomes unstable following an update, Omarchy provides three recovery layers according to manual/45-troubleshooting.md.

Rollback via system snapshots. Use the built-in system-snapshot feature to revert to the state captured before the update. This functionality is documented in manual/47-system-snapshots.md.

Generate a diagnostic log. Run the debug utility to collect system information:

omarchy-debug            # writes to /tmp/omarchy-debug.log

omarchy-debug --print    # outputs log to terminal

Attach this log when requesting help on the #omarchy-help Discord channel.

Reinstall default configurations. Execute omarchy-reinstall to restore the configuration hierarchy defined in the config/ directory and reinstall the base package set. This command invokes the same mechanisms used by omarchy-refresh-config and the original install scripts.

Fixing Display Scaling and Oversized Applications

Omarchy assumes a 2× Hi-DPI display by default, setting GDK_SCALE=2 via the monitor configuration. On standard 1× screens, applications may appear oversized.

Edit the monitor configuration to adjust scaling:

sed -i 's/local omarchy_gdk_scale = 2/local omarchy_gdk_scale = 1/' \
    ~/.config/hypr/monitors.lua

After modifying the file, restart the compositor with omarchy-restart-quickshell or log out and back in. For Spotify specifically, use the built-in shortcuts Ctrl-Minus and Ctrl-Plus to adjust UI scaling independently.

Reference: manual/45-troubleshooting.md and manual/33-monitors.md.

Restoring Traditional Caps Lock Behavior

By default, Omarchy repurposes Caps Lock as the xcompose key for quick emoji insertion. To restore traditional Caps Lock functionality, modify the input configuration in ~/.config/hypr/input.lua:

hl.config({
  input = {
    kb_options = "compose:ralt",   -- remap xcompose to Right-Alt
  },
})

Save the file and restart the compositor (omarchy-restart-quickshell) or log out to apply changes.

Reference: manual/45-troubleshooting.md.

Restarting Wi-Fi, Bluetooth, Audio, and Trackpad Subsystems

When specific hardware interfaces stop responding, avoid a full system reboot by restarting the individual subsystem. These commands are thin wrappers around the corresponding system services:

omarchy restart-wifi      # reloads NetworkManager

omarchy restart-bluetooth # restarts the Bluetooth service

omarchy restart-audio     # reloads pulse/pipewire audio

omarchy restart-trackpad  # reloads libinput configuration

Access these options via the Omarchy menu under Update > Hardware, or invoke them directly from the terminal. The menu definition resides in default/omarchy-menu.jsonc.

Configuring External Speakers and Audio Output

If external speakers fail to play, select the desired output device as Primary in the volume pop-up by clicking the speaker icon on the right side of the Omarchy bar. To script this selection, use pactl:

pactl set-default-sink <sink-name>

Managing Laptop Speaker Equalization

Omarchy ships with automatic speaker equalization profiles that may alter audio character. Check and modify the tuning status using the CLI:

omarchy audio tuning status   # displays "enabled" or "disabled"

omarchy audio tuning off      # disables the built-in EQ

Reference: manual/45-troubleshooting.md.

Resetting Sudo Access After Lockout

If you are locked out after multiple failed password attempts, switch to a new TTY with Ctrl+Alt+F2, log in as root or a user with sudo privileges, and reset the failure counter:

sudo faillock --reset --user <your-username>

Return to the graphical session with Ctrl+Alt+F1 (or the appropriate virtual terminal).

Resolving 1Password Authorization Failures

Authorization prompts may fail due to two common configuration issues. First, verify that Hardware Acceleration is enabled in Settings → Advanced → Use Hardware Acceleration, then reboot. Second, ensure the 1Password application is running before invoking the SSH Agent or CLI tools, as the authorization prompt requires an active process to display.

Reference: manual/45-troubleshooting.md.

Generating and Sharing Diagnostic Reports

The omarchy-debug command, located at bin/omarchy-debug, serves as the primary diagnostic utility. Beyond local logging, it supports uploading reports for community assistance:

omarchy-debug --upload      # upload to Omarchy crash-reporting endpoint

The implementation follows the crash-reporting skill documented in default/agents/skills/diagnose-crash/reporting.md. This workflow writes comprehensive system information to /tmp/omarchy-debug.log, capturing the state needed to troubleshoot Omarchy issues remotely.

Resetting and Refreshing Configuration Files

Configuration files reside in ~/.config/hypr/ and ~/.config/omarchy/, as detailed in docs/file-layout.md. To refresh specific configuration files without full reinstallation:

omarchy-refresh-config hypr/hyprland.lua

For a complete reset of the configuration hierarchy and base packages, use omarchy-reinstall. This command restores defaults without affecting user data.

Summary

• Diagnostic collection: Run omarchy-debug to generate /tmp/omarchy-debug.log and use --upload to share with support.
• Configuration locations: Edit files in ~/.config/hypr/ and ~/.config/omarchy/; use omarchy-reinstall to restore defaults.
• Display scaling: Change omarchy_gdk_scale from 2 to 1 in ~/.config/hypr/monitors.lua for low-DPI screens.
• Subsystem restarts: Use omarchy restart-wifi, restart-bluetooth, restart-audio, and restart-trackpad before rebooting.
• Audio management: Control laptop speaker EQ with omarchy audio tuning off and switch outputs via pactl set-default-sink.
• Authentication recovery: Reset sudo lockouts with faillock --reset from an alternate TTY.

Frequently Asked Questions

Where does Omarchy store its configuration files?

Omarchy stores user-specific configurations under ~/.config/hypr/ for window manager settings and ~/.config/omarchy/ for desktop environment settings. The docs/file-layout.md file in the repository describes the complete hierarchy, including where shell scripts, binaries, and default templates reside.

How do I generate a debug log to report an Omarchy issue?

Execute omarchy-debug in your terminal to create a comprehensive system report at /tmp/omarchy-debug.log. Add the --print flag to view the output directly, or use --upload to submit it to the crash-reporting endpoint. Attach this file when posting to the #omarchy-help Discord channel.

Why are my applications displaying too large on Omarchy?

Omarchy defaults to GDK_SCALE=2 assuming Hi-DPI displays. Edit ~/.config/hypr/monitors.lua and change omarchy_gdk_scale from 2 to 1, then restart the compositor. This scaling factor is applied via the monitor configuration as documented in manual/33-monitors.md.

What should I do if I get locked out of sudo?

Switch to a text console using Ctrl+Alt+F2, log in as root or another administrative user, and run sudo faillock --reset --user <your-username> to clear the failed authentication attempts. Return to your graphical session with Ctrl+Alt+F1 to regain normal access.

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