# When Omarchy Breaks > A calm repair kit for Omarchy: a symptom-to-fix cheat card, rolling back with system snapshots, reading logs, rescuing a desktop that will not start, fixing Wi-Fi, sound, sleep and display problems, getting help well, and reinstalling without losing your files. --- # When Omarchy Breaks Sooner or later you will press `Super + Space` and nothing will happen, or an update will finish and the screen will look wrong, or the Wi-Fi will vanish five minutes before a call. On a desktop where everything is a file you can edit, that moment feels worse than it is: you have more power than before, so it seems you also have more ways to have ruined it. You have not. Omarchy takes a safety snapshot before every update, keeps your own files separate from its files, and ships commands made for exactly this. This guide gives you the order of operations: the smallest fix first, the big hammer last, and a clear idea of what each one touches. Checked against Omarchy 4.0.4. ## Prerequisite You should be comfortable opening a terminal and running a command. If that is still new, read [The Terminal & Shell, Explained](/guides/the-terminal-and-shell) first. It also helps to know what happens between pressing the power button and seeing your desktop, which [How Your Computer Boots](/guides/how-your-computer-boots) covers. This guide is the last in the Omarchy category and leans on the sibling guides, especially [Making Omarchy Comfortable](/guides/making-omarchy-comfortable) (where your config files live) and [Installing and Updating Software on Omarchy](/guides/installing-and-updating-software-on-omarchy) (how updates work). ## How to read this - **Something is broken right now?** Open [the cheat card](01-the-cheat-card-and-the-repair-ladder.md) and find your symptom. If an update caused it, go straight to [rolling back](02-snapshots-and-rolling-back.md). - **Calm and want to be ready?** Read in order, then make a snapshot and a config backup before your next risky change. Ten minutes now is worth an evening later. ## The phases 1. **[The Cheat Card and the Repair Ladder](01-the-cheat-card-and-the-repair-ladder.md)** - symptom to fix at a glance, and the five rungs from "restart one thing" to "reinstall". 2. **[Snapshots and Rolling Back](02-snapshots-and-rolling-back.md)** - how Omarchy 4 snapshots, how to roll back from the boot menu, and what a rollback does not touch. 3. **[Reading Logs and Rescuing a Desktop That Will Not Start](03-reading-logs-and-rescuing-a-dead-desktop.md)** - journalctl, the update log, a text-mode login, and fixing a config you broke. 4. **[Hardware Gremlins, Getting Help, and Reinstalling](04-hardware-gremlins-getting-help-and-reinstalling.md)** - Wi-Fi, sound, sleep, displays, asking for help in a way that gets answers, and reinstalling without losing data. > Not covered here: installing Omarchy from scratch is in [Installing Omarchy](/guides/installing-omarchy), and plugins start at [Omarchy Plugins and the Marketplace](/guides/omarchy-plugins-and-the-marketplace). --- # The Cheat Card and the Repair Ladder Something is wrong and your heart rate is up. Start with the table below, find the row that looks like your problem, and do the first thing in it. Most rows are one command or one menu click. The rest of this guide explains why each fix works, so that next time you can reason instead of look it up. ## The cheat card | Symptom | Calm first move | |---|---| | An update finished and the desktop is broken or will not start | Restart, pick the snapshot from before the update in the boot menu. See [Phase 2](02-snapshots-and-rolling-back.md). | | The update ended with an "initramfs generation may have failed" warning | Do not reboot yet. Read the update log. See [Phase 3](03-reading-logs-and-rescuing-a-dead-desktop.md). | | The update refuses to start, complaining about disk space | Free space on `/` first. See [Phase 3](03-reading-logs-and-rescuing-a-dead-desktop.md). | | The bar, menu, or panels are frozen or blank | _Update > Process > Shell_, or run `omarchy restart shell` | | Wi-Fi, Bluetooth, audio, or the trackpad stopped working | _Update > Hardware_ and pick the one that broke. See [Phase 4](04-hardware-gremlins-getting-help-and-reinstalling.md). | | You edited a config and now a key, monitor, or setting misbehaves | Put your backup back, or `omarchy refresh config hypr/bindings.lua` (it saves a timestamped backup of your version first) | | Everything looks huge on a normal-density monitor | Set `local omarchy_gdk_scale = 1` in `~/.config/hypr/monitors.lua` | | External speakers are silent | Pick them as the output in the Audio panel (`Super + Ctrl + A`) | | Caps Lock does nothing | Working as designed: it is the compose key. See [Phase 4](04-hardware-gremlins-getting-help-and-reinstalling.md). | | Locked out after too many wrong passwords | The manual's fix is a text login on `Ctrl + Alt + F2`. See [Phase 3](03-reading-logs-and-rescuing-a-dead-desktop.md) for the caveat. | | You need to ask for help | `omarchy debug`, then the `#omarchy-help` channel. See [Phase 4](04-hardware-gremlins-getting-help-and-reinstalling.md). | | Your configs look corrupted beyond repair | `omarchy reinstall` (this overwrites your config changes) | ## Three layers, three owners The table looks like a grab bag, but every row follows one idea. Your Omarchy machine is built from layers that different people own, and a repair only helps if it touches the layer that is broken. | Layer | Where it lives | Who owns it | What repairs it | |---|---|---|---| | Running programs | Memory | Nobody, it resets | Restarting the piece | | Your config and files | `~/.config`, the rest of your home folder | You | Your backup, `omarchy refresh config`, `omarchy reinstall configs` | | Omarchy and system packages | `/usr/share/omarchy` and the rest of the system | Omarchy and pacman | A snapshot rollback, `omarchy reinstall pkgs` | The manual puts it in one sentence: the dotfiles in `~/.config` are your files, and the files in `/usr/share/omarchy` belong to Omarchy. Updates replace the second kind and leave the first alone. That split has a consequence people miss. **A snapshot rollback rewinds the system layer, not your home folder.** If you broke `bindings.lua`, rolling back will not fix it, because `bindings.lua` was never part of what gets rewound. And if an update broke the system, editing your config will not fix it. Naming the layer before you act is most of the skill. > 💡 **Key point.** Before you run anything, ask: "Did I change this, or did an update change this?" Your own edit means a config-layer fix. An update means a system-layer fix, and the rollback is your first move. ## The repair ladder Fixes are ordered from smallest to largest. Climb only as far as you need, because each rung touches more than the last. ```mermaid flowchart TD A["1. Restart one piece"] --> B["2. Refresh one config"] B --> C["3. Roll back a snapshot"] C --> D["4. omarchy reinstall"] D --> E["5. Reinstall from the ISO"] ``` 1. **Restart one piece.** Restarting the shell, Wi-Fi, audio, or trackpad costs nothing and clears most "it worked five minutes ago" problems. Reaching for a reboot first throws away the clue of which piece failed. 2. **Refresh one config.** `omarchy refresh config ` copies the shipped version of one file into `~/.config` and saves yours next to it as a timestamped `.bak` file. 3. **Roll back a snapshot.** Rewinds the system to the moment before the last update. Your home folder stays as it is. 4. **`omarchy reinstall`.** Reinstalls the default Omarchy packages and resets your configs to the defaults. Your config changes are overwritten. 5. **Reinstall from the ISO.** A full reinstall. A full-disk install wipes the drive you select, so back up first. The manual's own advice for a bad update matches this order: try the rollback, then run `omarchy debug` to ask for help, and only then reinstall the defaults. ⚠️ **Gotcha.** The ladder is not a straight line for every problem. A dead Wi-Fi service belongs on rung 1 and never needs rung 3. A bad update goes straight to rung 3 and skips 1 and 2. Match the rung to the layer, not to how frightened you feel. Check yourself before moving on: ```quiz [ { "q": "You edited ~/.config/hypr/bindings.lua an hour ago and a hotkey now misbehaves. Which repair targets the right layer?", "choices": [ "Roll back to the snapshot from the last update", "Restore your backup of bindings.lua, or run omarchy refresh config hypr/bindings.lua", "Reinstall from the ISO" ], "answer": 1, "explain": "bindings.lua lives in your home folder, which is your layer. A snapshot rollback rewinds the system but not /home, so it would not touch this file at all.", "why": [ "A rollback restores the root filesystem, not your home folder, so your edited file stays exactly as it is.", null, "That works but wipes a drive to fix one file. Always take the smallest rung that touches the broken layer." ] }, { "q": "Who owns the files in /usr/share/omarchy?", "choices": ["You, so edit them freely", "Omarchy, and updates overwrite them", "Nobody, they are temporary"], "answer": 1, "explain": "Those files belong to Omarchy and come from packages, so an update replaces them. Put your changes in ~/.config instead." }, { "q": "The Wi-Fi died after a suspend and nothing else is wrong. What is the best first move?", "choices": [ "Restart only the Wi-Fi piece from Update > Hardware", "Run omarchy reinstall", "Roll back the last snapshot" ], "answer": 0, "explain": "Restarting one subsystem is the smallest rung and clears most it-worked-a-minute-ago problems. It also tells you which piece failed." } ] ``` ## Recap 1. Find your symptom on the cheat card and do its first move before anything else. 2. Three layers: running programs, your files in `~/.config` and your home folder, and Omarchy's system files. 3. A snapshot rollback rewinds the system but not `/home`, so it cannot fix a config you edited. 4. Climb the ladder from smallest to largest: restart a piece, refresh a config, roll back, `omarchy reinstall`, ISO. 5. Ask "did I change this, or did an update?" before you pick a rung. Next up, [Snapshots and Rolling Back](02-snapshots-and-rolling-back.md): how the safety net is made, and how to use it. --- # Snapshots and Rolling Back You ran the update, restarted, and the desktop you knew is gone. The instinct is to investigate: what changed, which package, which log. Resist it for a few minutes. Omarchy made you a save point before the update started, and going back to it is faster than understanding the damage. ## What a snapshot is A snapshot is a frozen record of how your system files looked at one moment, like a save point in a game. You can keep playing from the present, or load the save and be exactly where you were. Omarchy makes them with snapper, a snapshot tool, and its snapper policy targets a btrfs root filesystem, a kind that makes snapshots cheap because it records the state without copying everything. Omarchy's own snapper policy is deliberately small: - It snapshots the root of the system (`/`), nothing else. - It keeps the **5 most recent** and discards older ones. - It takes no timed snapshots, only the ones triggered by an update or by you. That last point matters. Your safety net is five save points, not a rolling history. After five updates, the snapshot from before the oldest one is gone. ## When Omarchy takes them Every `omarchy update` follows the same sequence, and the snapshot is taken before anything changes: ```mermaid flowchart LR A["Confirm"] --> B["Snapshot"] B --> C["Packages"] C --> D["Migrations"] D --> E["Restart checks"] ``` *What just happened:* after you confirm, Omarchy snapshots first, then updates packages, then runs migrations (small scripts that bring your setup in line with the new release), then asks about any restarts. If it fails anywhere after the second box, the save point already exists. This is also why Omarchy blocks a bare `sudo pacman -Syu`. The guard stops the upgrade and points you to `omarchy update`, because a direct upgrade skips the snapshot and the migrations. The manual's wording is that you "miss the snapshot, migrations, and configuration updates." Before a change you are nervous about, such as editing a lot of config or trying a risky package, make your own: ```console $ omarchy snapshot create Create system snapshot Snapshots can be selected during boot. ``` *What just happened:* those two lines are what the command prints. It asked snapper for a new snapshot and then trimmed the list back to five. If snapper has nothing configured, the command refuses loudly instead of pretending: ```console $ omarchy snapshot create No Snapper configs found, so no snapshot was created. ``` ⚠️ **Gotcha.** That message is the one to take seriously. Silence from a snapshot command would look like success, so Omarchy prints it on purpose. If you ever see it, you have no save point, and the next update is not recoverable this way. ## Rolling back from the boot menu Snapshots work only on installs using the **Limine** bootloader, which has been the default since Omarchy 2.0. They do not work on GRUB or systemd-boot. The boot menu is titled "Omarchy Bootloader". The steps, from the manual: 1. **Restart** the machine and open the boot menu. 2. **Pick a snapshot** by its date. The Omarchy version at the time of the snapshot shows in the bottom-left corner, so you can tell the pre-update one from an older one. 3. **Boot into it.** A notification appears telling you that you are in a bootable snapshot. 4. **Restore.** Click the notification to start the restoration, or run `omarchy snapshot restore` in a terminal. That command runs `limine-snapper-restore` for you. The boot menu is the whole point. It lives before your desktop, so it works even when the desktop will not start at all. **If you boot straight to the decryption screen.** Omarchy has a _Setup > Direct Boot_ option that skips the menu. With it on, you must choose Limine from your firmware's boot menu (the BIOS or UEFI boot picker) to reach your snapshots. Running _Setup > Direct Boot_ again removes the shortcut. It refuses to run on American Megatrends and Apple firmware. > 💡 **Key point.** If you never touch the boot menu, you will not know how to reach it on the day you need it. Restart once on a calm afternoon and look at it. ## What a rollback does not touch A restore brings back your **root filesystem**, but **not your `/home`**. The manual says what follows from that: - It is a fix for a broken system update. It is not a way to recover files you deleted. - Your `~/.config` stays as it is. If the older package version expects an older config format and your files were already migrated to a new one, you have to sort that out by hand. So a rollback is safe for your documents. It is also exactly why a bad config edit survives a rollback, as [Phase 1](01-the-cheat-card-and-the-repair-ladder.md) showed. Rolling back puts you on the old version. The update that caused the trouble is a problem for another day, so ask in `#omarchy-help` before you update again. ## Your turn: the update that broke the desktop You ran _Update > Omarchy_ twenty minutes ago and restarted. The desktop comes up with a bare wallpaper and no bar. You can open a terminal with `Super + Return`. You are presenting at 10:00, and it is 9:20. Every move costs real minutes. ```scenario { "title": "9:20 - the bar is gone after the update", "brief": "You updated Omarchy twenty minutes ago and rebooted. The wallpaper is there but the bar is missing and Super + Space does nothing. Super + Return still opens a terminal. You present at 10:00 and every move you make costs minutes.", "prompt": "What do you do first?", "clock": { "unit": "min", "running": "burned", "resolved": "to a working desktop" }, "resolvedHeading": "You are back. Here is how that went.", "actions": [ { "id": "restart-shell", "label": "Run omarchy restart shell", "cost": 2, "reveals": "$ omarchy restart shell\n(the wallpaper flickers, the bar does not return)", "note": "A cheap and sensible first try, and it rules out a one-off crash. Here it changes nothing." }, { "id": "journal", "label": "Read the warnings with journalctl -b -p 4..1", "cost": 8, "reveals": "$ journalctl -b -p 4..1\n(hundreds of warning lines, most of them harmless noise on any boot)", "note": "Reading logs is how you learn why. It is the right move for a normal bug and an expensive one when a save point is already sitting there." }, { "id": "update-log", "label": "Read /tmp/omarchy-update.log", "cost": 5, "reveals": "$ omarchy update analyze logs\n(no failure conditions reported)", "note": "No known failure pattern. Useful to know, and it still does not give you a working desktop." }, { "id": "pacman", "label": "Run sudo pacman -Syu to pull the newest fixes", "cost": 4, "reveals": "The Omarchy guard aborts the transaction and points you to omarchy update.", "note": "Reasonable if you know Arch. Omarchy blocks it on purpose, because a direct upgrade skips the snapshot and the migrations." }, { "id": "help", "label": "Run omarchy debug and upload the log, then wait for answers in #omarchy-help", "cost": 12, "reveals": "You post the log link and the question. People help, and it takes a while.", "note": "Asking is good practice and you will do it in Phase 4. It is slow when a faster fix is available, so roll back first and ask afterwards." }, { "id": "reinstall", "label": "Run omarchy reinstall", "cost": 15, "reveals": "This will reinstall all default Omarchy packages and reset default configs.\nWarning: user config changes will be overwritten.", "note": "It would probably work, and it overwrites your config changes to fix a problem a rollback could undo without touching them." }, { "id": "rollback", "label": "Restart, pick the snapshot from before the update in the boot menu, then restore it", "cost": 6, "resolves": true, "note": "Back on the old version, home folder untouched. You still do not know what broke, and you did not need to." } ], "debrief": { "ideal": 6, "text": "After an update, the move that ends the problem is the one you can make before you understand it. Roll back, present, and investigate on your own time.", "notes": [ { "when": "if-taken", "action": "journal", "text": "You read the logs before rolling back. That instinct is correct for most bugs. When a snapshot exists, understanding can wait until the deadline is safe." }, { "when": "if-taken", "action": "reinstall", "text": "You reached for the largest rung when a smaller one covered it. Reinstalling resets your configs, which a rollback would have left alone." }, { "when": "if-not-taken", "action": "restart-shell", "text": "Restarting the shell is worth two minutes first, because a one-off crash is the cheapest explanation." } ] } } ``` Check yourself before moving on: ```quiz [ { "q": "You want a save point before editing a lot of config. What do you run?", "choices": ["omarchy snapshot create", "omarchy update -y", "omarchy reinstall"], "answer": 0, "explain": "omarchy snapshot create asks snapper for a snapshot of the system root. Updates make one automatically, but this makes one on demand.", "why": [ null, "That runs a full update, which changes the system rather than saving it.", "That resets your configs to defaults, so it is the opposite of a save point." ] }, { "q": "After you restore a snapshot, what is true of your home folder?", "choices": [ "It is rewound to the same moment as the system", "It is left exactly as it was, including ~/.config", "It is wiped and recreated from defaults" ], "answer": 1, "explain": "A restore reverts the root filesystem but not /home. That is why it fixes a bad update and cannot recover deleted personal files." }, { "q": "Your machine boots straight to the decryption screen and skips the menu. How do you reach a snapshot?", "choices": [ "You cannot, snapshots are gone", "Choose Limine from the firmware's boot menu first", "Reinstall Omarchy" ], "answer": 1, "explain": "With Direct Boot on, the firmware goes straight to Omarchy. Pick Limine in the BIOS or UEFI boot menu to get the snapshot list, or run Setup > Direct Boot again to remove the shortcut." } ] ``` ## Recap 1. Omarchy snapshots the system root before every update, keeps the 5 most recent, and takes no timed snapshots. 2. `omarchy snapshot create` makes your own, and "No Snapper configs found" means you have no save point. 3. To roll back: restart, pick the snapshot in the Limine menu, boot it, then restore from the notification or with `omarchy snapshot restore`. 4. A restore rewinds the system root only. `/home` and `~/.config` are left as they are. 5. After a bad update, roll back first and investigate later. Next up, [Reading Logs and Rescuing a Desktop That Will Not Start](03-reading-logs-and-rescuing-a-dead-desktop.md): when the problem is yours, or the rollback is not enough. --- # Reading Logs and Rescuing a Desktop That Will Not Start A rollback fixes a bad update. It does not fix the config you edited last night, a disk that filled up mid-update, or a problem you want to understand before you try again. For those you need two skills: reading what the machine wrote down, and getting a login when the graphical desktop will not appear. ## Logs are the machine's diary Almost everything on a modern Linux system writes its complaints to one place, the **journal**, and you read it with `journalctl`. It is noisy on purpose: it records everything and leaves the sorting to you. These are the views worth knowing. | What you want | Command | |---|---| | Warnings and worse from this boot | `journalctl -b -p 4..1` | | The last 100 lines the Omarchy shell logged | `journalctl -t omarchy-shell -n 100 --no-pager` | | The shell's log, live as you reproduce the problem | `journalctl -t omarchy-shell -f` | | Kernel messages (hardware and drivers) | `sudo dmesg` | | All of the above in one report | `omarchy debug --print --no-sudo` | What the flags mean: `-b` is "this boot only", `-p 4..1` is a priority range from warning up to alert (so it hides the chatter), `-t` filters by the tag a program logs under, `-n 100` is the last 100 lines, `-f` follows new lines as they arrive, and `--no-pager` prints straight to the screen instead of opening a scrolling viewer. The `omarchy-shell` tag is useful because the desktop shell (the bar, menus, panels, lock screen) is one long-running program. If a bar or panel will not draw, that tag is where it says why. > 💡 **Key point.** Do not read a log top to bottom. Find the time you did the thing that broke, and read the first warning or error near it. Many warnings appear on every healthy boot, so a line that is new, repeated, or that appears right before the failure is the one that matters. ## The update log and the warning not to ignore `omarchy update` records a transcript of everything it printed in `/tmp/omarchy-update.log`. After an update, Omarchy can scan it for known failures: ```bash omarchy update analyze logs ``` The one check it runs today looks for a failed **initramfs** build and prints this warning: ```text Error: Initramfs generation may have failed. Review logs before restart. ``` An initramfs is the small image your kernel loads at the very start of a boot, before your real filesystem is available. On an encrypted machine it holds what is needed to unlock and mount the disk. If the build failed and you reboot, the next boot can fail before the desktop, or even the login, appears. ⚠️ **Gotcha.** If you see that warning, **do not reboot**. Read `/tmp/omarchy-update.log`, copy it somewhere safe (`/tmp` is a temporary folder), and ask for help with it (see [Phase 4](04-hardware-gremlins-getting-help-and-reinstalling.md)). If you reboot anyway and it will not start, you still have the snapshot Omarchy took before the update, reachable from the boot menu. Two other update failures are common: - **Not enough free space.** Omarchy checks free space on `/` before it asks you to confirm, and stops if there is less than 10 GiB. Make room first, for example with _Remove > Package_ or `omarchy update pkg prune` (which prunes superseded versions from the pacman package cache). A bypass exists (`OMARCHY_UPDATE_FORCE=1`), but a disk that fills up halfway through an update is exactly the failure you are avoiding, so use it only if you know you have room. - **An update that stopped partway.** Migrations run after the packages. `omarchy migrate --pending` lists any that have not finished, and `omarchy migrate` runs them. ## When the desktop will not start Work out how far the boot got, because that tells you where to look. | What you see | Meaning | Go to | |---|---|---| | No boot menu, firmware screen only | Below Omarchy | Your firmware boot menu; see Direct Boot in [Phase 2](02-snapshots-and-rolling-back.md) | | Boot menu, then the machine fails to start | The system layer | Roll back from the boot menu | | Decryption prompt, login, then a black screen or no desktop | Your session or your config | A text login, below | ### A text login A **TTY** is a plain text console: no windows, no mouse, only a login prompt. Your desktop is one program that runs on top of it, so when the desktop fails, the text console usually still works. The manual uses `Ctrl + Alt + F2` to reach one: 1. Press `Ctrl + Alt + F2`. 2. Log in with your username and password. 3. Look at the evidence: ```bash journalctl -b -p 4..1 | less omarchy debug --print --no-sudo | less ``` (`less` is a viewer: arrow keys scroll, `q` quits.) If you are new to this kind of prompt, [The Terminal & Shell, Explained](/guides/the-terminal-and-shell) covers the basics. ### Fixing a config you broke Your Hyprland config is Lua, and `~/.config/hypr/hyprland.lua` loads your files in a fixed order: the Omarchy defaults first, then `monitors`, `input`, `bindings`, `looknfeel`, and `autostart`. So the suspect is almost always the file you edited last. Your files load after the defaults, so a mistake in one of them can override a working default. 1. **Put your backup back.** If you followed the habit below, copy it over the broken file. 2. **Or edit the file and undo your last change.** Use any terminal editor you have; Neovim (`nvim`) ships with Omarchy. Comment out the lines you added by starting each with `--`, which is a Lua comment, then save with `:wq`. 3. **Restart the session.** In a text login, `reboot` is enough. If you are still in a working desktop, `omarchy refresh config hypr/bindings.lua` copies the shipped file over yours and keeps a backup of yours beside it. `omarchy refresh hyprland` does that for all the Hyprland Lua files, and _Update > Config > Hyprland_ is the menu route. The refresh command reads the `OMARCHY_PATH` variable, which a bare text login may not have set, so do not count on it there. Your own backup or the edit above is the reliable path there. The habit that makes all of this cheap, before you edit any config: ```console $ cp ~/.config/hypr/bindings.lua ~/.config/hypr/bindings.lua.bak ``` *What just happened:* you made a copy next to the original. If the edit goes wrong, the fix is copying it back, with no searching and no guessing. ### Locked out of your own login If you typed your password wrong too many times and are locked out, the manual's advice is to press `Ctrl + Alt + F2` for a text login, sign in as root, and run: ```bash faillock --reset --user [your-username] ``` That clears the lockout counter. One caveat: Omarchy's 4.0.1 release notes list removing a "sudo lockout reset command" among security fixes, and we could not confirm that the manual's steps work unchanged on 4.0.4. If they do not, ask in `#omarchy-help` rather than guessing. ## Your turn: read the evidence Check your reading skills: ```exercise [ { "type": "predict", "task": "Type the journalctl command that shows only warnings and worse from the current boot, using the priority range 4..1.", "accept": ["/^journalctl\\s+(-b\\s+-p\\s*4(\\.\\.1)?|-p\\s*4(\\.\\.1)?\\s+-b)\\s*$/i"], "hint": "Two flags: one for 'this boot only', one for the priority range." } ] ``` ```quiz [ { "q": "The update ends with: Initramfs generation may have failed. Review logs before restart. What do you do?", "choices": [ "Reboot right away, it is probably fine", "Do not reboot yet, read /tmp/omarchy-update.log and get help", "Run omarchy reinstall" ], "answer": 1, "explain": "The initramfs is needed early in the next boot. Review before restarting, and remember the pre-update snapshot is your net if you do reboot into trouble.", "why": [ "A failed initramfs can stop the next boot before the desktop or login appears.", null, "A reinstall resets your configs and does not address a failed boot image." ] }, { "q": "Which command follows the Omarchy shell's log live while you reproduce a problem?", "choices": [ "journalctl -t omarchy-shell -f", "journalctl -b -p 4..1", "omarchy update analyze logs" ], "answer": 0, "explain": "-t filters by the omarchy-shell tag and -f follows new lines as they arrive." }, { "q": "The desktop is black after you edited monitors.lua. You press Ctrl + Alt + F2 and log in. What is a reliable fix?", "choices": [ "Roll back the last snapshot", "Restore your backup of monitors.lua or comment out your change, then reboot", "Edit the files in /usr/share/omarchy" ], "answer": 1, "explain": "monitors.lua is in your home folder, so a rollback will not touch it. Never edit /usr/share/omarchy, which belongs to Omarchy and is overwritten on update." } ] ``` ## Recap 1. The journal is the diary: `journalctl -b -p 4..1` for warnings this boot, `journalctl -t omarchy-shell` for the shell. 2. `omarchy update analyze logs` reads `/tmp/omarchy-update.log`. On an initramfs warning, do not reboot. 3. Updates stop under 10 GiB free on `/`. Make room instead of forcing it. 4. When the desktop will not start, `Ctrl + Alt + F2` gives you a text login and the same logs. 5. A broken config is fixed by restoring your backup or undoing your last change, since your files load after the defaults. 6. Back up a config file before editing it. Next up, [Hardware Gremlins, Getting Help, and Reinstalling](04-hardware-gremlins-getting-help-and-reinstalling.md): the problems that are not your fault, and the last resort. --- # Hardware Gremlins, Getting Help, and Reinstalling Some failures are not your edit and not an update: a headset that will not reconnect, a trackpad that died after suspend, a display at the wrong size. They feel like the machine betraying you, but most clear up with a restart of one small piece. When they do not, the way you ask for help decides how fast you get it. And if everything else fails, you can reinstall in stages without losing your files, provided you backed them up first. ## Restart the piece before you reboot A reboot restarts everything and hides which part failed. Omarchy has a restart for each piece that commonly misbehaves. The menu route is _Update > Hardware_, and each has a command: | Symptom | Menu | Command | |---|---|---| | Wi-Fi gone | _Update > Hardware > Wi-Fi_ | `omarchy restart wifi` | | Bluetooth headset will not reconnect | _Update > Hardware > Bluetooth_ | `omarchy restart bluetooth` | | Sound vanished (for example after unplugging a monitor) | _Update > Hardware > Audio_ | `omarchy restart audio` | | Trackpad dead after a suspend | _Update > Hardware > Trackpad_ | `omarchy restart trackpad` | | Bar or panels broken | _Update > Process > Shell_ | `omarchy restart shell` | The manual says reloading one of these "clears up the majority" of "it worked five minutes ago" situations. If a restart works, you also learned something: that piece needs attention, not the whole machine. ## The usual suspects **Wi-Fi.** Networking is NetworkManager, driven by the panel on `Super + Ctrl + W`. `nmtui` gives the same controls in the terminal. If a router shares one name across 2.4GHz, 5GHz, and 6GHz and your laptop clings to the slow one, `omarchy network band` shows the band and `omarchy network band 5` pins it (`auto` unpins). If the clock itself has drifted, _Update > Time_ restarts time synchronization. **Sound.** External speakers that stay silent are usually not selected as the output. Open the Audio panel (`Super + Ctrl + A`) and pick them. If a laptop's built-in speakers sound off, some machines get an automatic tuning: `omarchy audio tuning status` tells you whether one is active and `omarchy audio tuning off` removes it. **Sleep.** Suspend and hibernate appear under _System_ (`Super + Escape`). If either misbehaves on your machine, `omarchy toggle suspend` shows or hides the suspend entry, so you can test whether it works consistently and hide it if not. Hibernation is set up with `omarchy hibernation setup`, which creates a swap area the size of your RAM on the boot drive (so you need that much free space) and requires the Limine bootloader. `omarchy hibernation remove` takes it out again. **Displays.** Omarchy assumes a high-density display. On a 1080p or 1440p monitor, apps look oversized until you set the scale in `~/.config/hypr/monitors.lua` (opened by _Setup > Monitors_): ```lua local omarchy_gdk_scale = 1 local omarchy_monitor_scale = 1 ``` Apps already open keep the old value, so close the oversized ones (or all windows with `Ctrl + Alt + Delete`) and reopen them. `Super + /` and `Super + Alt + /` step the scale up and down, and `omarchy display text size 14` changes only the text size. For a laptop whose screen stays dark after you unplug an external monitor, `Super + Ctrl + Delete` toggles the laptop display, and `omarchy hw recover internal monitor` clears the internal-monitor-disable toggle when no external display is connected. **GPU.** On laptops with two GPUs, _Trigger > Hardware > Hybrid GPU_ switches between dedicated and integrated mode (through `supergfxd`). `omarchy hw hybrid gpu` detects whether you have such a setup. Omarchy's troubleshooting pages do not cover driver problems beyond this, so for anything deeper, collect a debug report and ask. **Firmware.** _Update > Firmware_ fetches BIOS, SSD, and dock updates your hardware has waiting. It may ask for a reboot. **Caps Lock.** It does nothing by design: Omarchy makes it the compose key, which powers quick emojis and completions. By default, pressing both Shift keys together turns Caps Lock on, and the next lone Shift press turns it off. To move the compose key elsewhere, edit `~/.config/hypr/input.lua`; the manual's example makes the right Alt key the compose key: ```lua hl.config({ input = { kb_options = "compose:ralt", }, }) ``` ## Getting help that gets answers Before you ask, collect evidence. `omarchy debug` writes a report to `/tmp/omarchy-debug.log` and then offers choices: view it, save it in your current directory, or (when the machine is online) upload it. ```bash omarchy version omarchy debug ``` The report holds your hostname, hardware details, kernel messages, the warnings from this boot's journal, and the list of installed packages. **Read it before you share it**, or print it with `omarchy debug --print` and look first. If you choose upload, it goes to `logs.omarchy.org` and you get a link to post. Add `--no-sudo` to skip the kernel messages if you would rather not run `sudo`. The community help channel is `#omarchy-help` on [the Omarchy Discord](https://omarchy.org/discord). A request that gets answered quickly has five parts: 1. **What you did,** in order ("ran Update > Omarchy, restarted"). 2. **What you expected and what happened instead.** 3. **What you already tried,** and what each attempt did. 4. **Your version and channel** (`omarchy version` and `omarchy version channel`). 5. **The debug log link.** > 💡 **Key point.** "My Wi-Fi is broken" gets guesses. "After Update > Omarchy, Wi-Fi scans but never connects; `omarchy restart wifi` did not help; log: link" gets answers. Having rolled back or not is also worth saying. ## Reinstalling in stages If a rollback and a config refresh did not fix it, reinstall, but choose the smallest version that touches your problem. | Command | What it does | What it overwrites | |---|---|---| | `omarchy reinstall pkgs` | Resets the package config to Omarchy's stable mirrors, downgrades anything newer than stable, and installs any default package that is missing | Custom pacman mirror and repository settings | | `omarchy reinstall configs` | Copies Omarchy's shipped user defaults over your home folder, and refreshes the bootloader, boot splash, and Neovim setup | Every shipped file you changed, including `~/.bashrc` and files under `~/.config` | | `omarchy reinstall` | Both of the above, after asking you to confirm, then offers to reboot | Both lists | It only replays files Omarchy itself ships, so your documents, projects, and photos are not on the list. But your edited dotfiles are, and the manual is blunt: all your user config changes "will be overwritten". **Back up first.** Copy anything you would miss to a second drive, and copy your own tweaks in particular: ```console $ cp -a ~/.config ~/config-before-reinstall $ cp ~/.bashrc ~/bashrc-before-reinstall ``` *What just happened:* you saved your current settings beside your home folder's other files. After the reinstall you can copy back only the changes you still want, one at a time. Keep that copy on another drive too, if the reinstall is happening because the disk is failing. The manual also recommends GNU Stow as a good way to back up your dotfiles. ### The last rung: the ISO Installing from the ISO is a full reinstall. A full-disk install wipes the drive you select, so a backup comes first, and the free-space option leaves other systems alone, as in a dual boot. Get the ISO from the [Omarchy 4.0.4 release page](https://github.com/basecamp/omarchy/releases/tag/v4.0.4) and compare its SHA256 with the one listed there. If you cannot reach your files at all, ask for help before you wipe the drive. ⚠️ **Gotcha.** _Setup > Reset Computer_ is not a reinstall. It is a factory reset meant for handing a machine to a new owner: it wipes every user account and everything in `/home`. Never use it to fix a problem. ## Your turn: write your recovery card Do this once while nothing is wrong. It takes ten minutes. ```exercise [ { "type": "task", "task": "Prepare for your next breakage: restart once and find the boot menu, check that snapshots exist, back up your config, and note where to ask for help.", "reveal": "Restart and look at the Omarchy Bootloader menu. Run omarchy snapshot create and confirm it does not print the No Snapper configs found message. Run cp -a ~/.config ~/config-backup. Save the link https://omarchy.org/discord and the channel name #omarchy-help.", "checklist": [ "I have seen the boot menu and know how to reach it", "omarchy snapshot create ran without the No Snapper configs found message", "My ~/.config and ~/.bashrc are copied somewhere safe", "I know my version (omarchy version) and where to ask for help" ] } ] ``` ```quiz [ { "q": "Your Bluetooth headset will not reconnect, but everything else works. What is the best first move?", "choices": [ "Reboot the machine", "Restart only Bluetooth from Update > Hardware", "Run omarchy reinstall" ], "answer": 1, "explain": "Restarting one piece is the smallest fix, and it shows you which piece failed. A reboot hides that, and a reinstall is far too large." }, { "q": "What does omarchy reinstall configs overwrite?", "choices": [ "Only files in /usr/share/omarchy", "The shipped files in your home folder you may have edited, such as ~/.bashrc and ~/.config", "Every file in your home folder, including documents" ], "answer": 1, "explain": "It replays Omarchy's shipped defaults over your home folder. Your own documents are not among those files, but your edited dotfiles are, so back them up first.", "why": [ "That folder belongs to Omarchy and is replaced by packages, not by this command.", null, "It only replays files Omarchy ships, so your own documents and projects are not on the list." ] }, { "q": "Which makes a help request most likely to get a useful answer?", "choices": [ "A screenshot and the words: it is broken", "What you did, what happened, what you tried, your version, and the omarchy debug log", "Posting in every channel at once" ], "answer": 1, "explain": "Helpers need steps, evidence, and context. The debug report gives them your hardware, package list, and warnings in one link." } ] ``` ## Recap 1. Restart the one piece that broke (`omarchy restart wifi`, `bluetooth`, `audio`, `trackpad`, `shell`) before you reboot. 2. Most hardware surprises have a cause: wrong audio output, display scale, a sleep feature, or Caps Lock being the compose key. 3. `omarchy debug` makes a report you can read first and then upload, view, or save. Ask in `#omarchy-help` with steps, expectations, attempts, version, and the log. 4. Reinstall in stages: `omarchy reinstall pkgs`, `omarchy reinstall configs`, or both. Your edited dotfiles are overwritten, so back them up. 5. The ISO is the last rung and wipes a full-disk target. `Reset Computer` is not a repair tool.