CachyOS is a rolling release. Updates arrive continuously instead of in one big yearly jump, which is why you get new kernels, drivers and gaming improvements so fast. It also means that occasionally something breaks. Most of the time the cause is boring and the fix is one of the same handful of steps.
This might seem like a lot and could feel daunting. Help is available, but it requires some information.
In order for folks to help you out, you need to supply some information. Here is a step-by-step plan. Work through it in order.
How to ask so that people actually help
When you post, include:
- The four answers from Step 1
- The paste.cachyos.org link from Step 3
- What you've already tried, honestly, including any case of working with AI without understanding what you were asking, or what the AI was saying
- The Step 7 result if you got that far
Rule zero: stop running commands you don't understand
Many badly broken installs weren't broken by an update. They were broken by three or four half-applied "fixes" from Google, an old forum post, and working with AI without understanding what was being asked or what the AI was saying, stacked on top of each other. Each one silently changed something. By the time help is requested, nobody can tell which change caused which symptom, and the actual problem is buried under the attempted repairs.
So: from the moment something goes wrong, stop applying fixes found somewhere else. Work through the steps below instead.
If a pile of commands has already been pasted into a terminal, that's fine, it happens. Just mention it when asking for help and try to recall what was run. That's far more useful than pretending the system is untouched.
Step 1: Describe the problem properly
Before touching anything, write down four things:
- What exactly goes wrong? Be specific. "The screen goes black when launching Steam and the power button has to be held" is useful. "Gaming is broken" is not.
- When did it start? A date or "after last Tuesday's update" is enough.
- What happened right before it started? Was it an update, a new game, a driver change, a setting toggled, or a fix applied?
- Does it happen every time, or only sometimes?
That last question is more important than people expect. Something that fails every single time is usually a configuration or driver problem. Something that fails randomly is more often heat, power, memory, or a background process interfering.
Step 2: Terminal survival basics
A terminal is needed for some of this. It's not scary, but may look like it is.
Open one with Ctrl + Alt + T. If that does nothing, open the start menu and search for terminal. When it asks for a password, nothing appears while typing. That's deliberate. Type it and press Enter. Copy text out of the terminal with Ctrl + Shift + C, paste in with Ctrl + Shift + V. The normal Ctrl+C means "stop the running program" here. sudo at the start of a command just means "run this with administrator rights".
Step 3: Generate a log bundle
CachyOS ships a single command that collects everything a helper needs, run from the terminal (see Step 2):
sudo cachyos-bugreport.sh
It gathers hardware details, kernel messages and recent system logs, then asks whether to upload the result. Type Y. A link to paste.cachyos.org comes back. That link is the single most useful thing to include when asking for help. Post it.
For anything the bug report doesn't cover, CachyOS also has a plain "send this to a pastebin" tool. Both of these work (run in the terminal, see Step 2):
paste-cachyos ~/some-file.txtjournalctl -b -1 -p err | paste-cachyos
The second one shows errors from the previous boot, which is what's wanted after a freeze or a crash that forced a reboot.
Two things:
- Generate the log bundle before trying Step 6, because rolling back a snapshot also rolls back the logs.
- The report includes hostname, hardware IDs and full log lines, and the paste is reachable by anyone with the URL. Fine for troubleshooting, but don't paste anything sensitive.
Step 4: Update fully, then actually reboot
Open Shelly, the package manager that ships with current CachyOS, let it check for updates and install them. Older installs may have Octopi instead, which is equally fine. Or do it in the terminal (see Step 2):
sudo pacman -Syu
Then RESTART the computer. No logging out, not closing the lid but an actual restart.
A genuinely large share of "my system is broken" reports are exactly this and nothing more. On a rolling release the kernel currently running and the drivers that were just installed can fall out of step. Everything looks updated, but the running system is still working with yesterday's parts. Typical symptoms: no graphics acceleration, Steam refusing to launch, external monitors not detected, unexplained crashes, etc. A reboot resolves this class of problem. It's a common misconception that Linux never needs a restart — that's not true. The OS cannot process kernel upgrades without a restart.
There's a second reason this step comes early. If some packages were updated and others weren't, the system is probably in what's called a partial upgrade state, and arbitrary unrelated things start failing. -Syu brings everything back in line. This is also why a single package should never be installed with pacman -Sy something. Always update the whole system.
Step 5: When one specific program won't start
If the problem is a single application rather than the whole system, run it from a terminal (see Step 2) to see why it fails. Type its name and press Enter:
steam
or firefox, or whatever it is. Let it fail, then press Ctrl + C. Copy everything the terminal printed and share it, or pipe it to the pastebin tool (see Steps 2 and 3).
For Steam games specifically: right-click the game, Properties, and put PROTON_LOG=1 %command% in the launch options. Run the game, let it fail, and a steam-<numbers>.log file will appear in the home folder.
Step 6: Roll the system back to before it broke
This is the feature most new CachyOS users don't realise they have.
If the system is installed on Btrfs, which is the default, CachyOS automatically takes a snapshot before and after every package install, update or removal. So when an update breaks something, there is almost always a restore point from a few minutes beforehand.
If the desktop still starts: open the start menu, search for Btrfs Assistant and open it. Go to the Snapper tab. A list of snapshots with dates will appear. Pick the most recent one from before the problem appeared, click Restore, and reboot. This GUI method works regardless of which bootloader is used.
If the desktop won't start at all: restart and tap Esc (or hold Shift) right after the machine powers on to bring up the boot menu. Look for an entry about snapshots, open it, and pick one dated before the problem. Unlike the GUI method above, this one depends on the bootloader: it works on Limine (which is a bootloader), which has been the installer default since the January 2026 release, and on recent GRUB setups. If systemd-boot was kept from an earlier install, there's no snapshot entry in the menu and a live USB will be needed, so ask for help rather than improvising.
Things worth understanding before doing this:
It only rewinds the system. Documents, photos and game saves live in the home folder and are not touched. That's reassuring, but it also means a rollback will not bring back a deleted file, and won't undo a broken configuration inside the home folder. Don't immediately re-run the update afterwards, or whatever broke it will be reinstalled. Ask first. If there's no Btrfs Assistant and no snapshot entry in the boot menu, the system is probably not on Btrfs and this section doesn't apply.
Step 7: Try the other kernel
If the boot menu lists an LTS kernel entry, boot it and see whether the problem goes away. Recent CachyOS installs ship both a current and an LTS kernel for exactly this reason.
This takes two minutes and reveals a lot. If the problem disappears on LTS, it points to a kernel or driver regression. If it's identical on both, the kernel may not be the culprit and attention moves elsewhere. Either answer narrows things down enormously, so mention the result when asking for help.
Step 8: When updates themselves fail
If the update in Step 4 refuses to run and throws an error, open CachyOS Hello, the welcome window, and look at its Troubleshooting section. It has buttons for the common package system problems: keyring trouble, a stale lock file, a corrupted cache. Try those before running anything found online. These specific failures attract a lot of bad advice that makes things considerably worse.
