# How to Troubleshoot Omarchy Issues: A Complete Diagnostic Guide

> Troubleshoot Omarchy issues effectively with our diagnostic guide. Learn to generate logs, reinstall settings, and restart services for smooth operation. Fix problems fast.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-19

---

**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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/manual/47-system-snapshots.md).

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

```bash
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:

```bash
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`](https://github.com/basecamp/omarchy/blob/main/manual/45-troubleshooting.md) and [`manual/33-monitors.md`](https://github.com/basecamp/omarchy/blob/main/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`:

```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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash
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`:

```bash
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:

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

omarchy audio tuning off      # disables the built-in EQ

```

*Reference:* [`manual/45-troubleshooting.md`](https://github.com/basecamp/omarchy/blob/main/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:

```bash
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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash
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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md). To refresh specific configuration files without full reinstallation:

```bash
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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.