CachyOS FAQ & Troubleshooting Guide

How to report an issue or bug to CachyOS

Don’t forget to use the tldr command to view a simplified version of the man pages for commands you are not familiar with. Example:

Some of the most common commands and descriptions for git:

tldr git

You can also combine tldr with a specific git command to get more detailed information about a parameter, for example:

tldr git add

Places to report

Github
Forum
Discord: Support Forum
- Before creating a new post. Please make sure to read the Support Guidelines & Information pinned in the channel.
  - Or if you think your issue can be solved quickly, use the #support channel
Reddit

Be patient and respectful

The CachyOS team and community are volunteers who work on this in their free time. Please be patient and respectful when interacting with them. Providing a high-quality bug report is the best way to get your issue resolved quickly.

If you ask a vague question or provide insufficient information. Then you might get a vague response too or no response at all.

Here is an example:

Good question:
- After a recent update (my last update was on DATE), my system fails to boot with a black screen. I have an NVIDIA GPU (model). I tried downgrading the linux-cachyos package to the previous version, but the issue persists. Here is the output of journalctl -b -1 and dmesg from the live environment.
Bad or vague question:
- My system is broken, please help me.
Otherwise you might end up looking like Abraham from this meme:

Describe your Issue

Here is a couple of things you should ask yourself about:

What is not working?
Does downgrading package X fix the issue?
Use the search function for equal issues
Did the issue appear after an update?
Have you made modifications on your own?
- Example: Adding an additional flag in a modprobe file
Is it hardware related? (e.g. GPU, WiFi, etc.)
Is it software related? (e.g. specific application, desktop environment, etc.)
Is it a fresh installation or did the issue appear after some time of usage?

How to gather logs

There are many ways to gather logs from your system. Here are a couple of examples and tools you can use:

Creating a general bug report

CachyOS provides a great tool to gather logs from the system called cachyos-bugreport.sh.
- This tool will collect logs from:
  - dmesg
  - journalctl
  - inxi (To collect hardware information)
- When the logs are collected, the user will be prompted to decide whether to upload them to our paste website.
- Run the following command in the terminal, and post the link with the bugs into the topic:
  Terminal window
```
sudo cachyos-bugreport.sh
```

Gathering logs from a program that is not starting

X program is no longer starting:
- There are many reasons why a graphical program might not start. The best way to gather logs for this kind of issue is to run the program from a terminal. This way you can see any error messages or output that might help diagnose the problem.
- Example:
  Terminal window
```
firefox
```
  - If Firefox fails to start, you might see an error message in the terminal that can help identify the issue.
  Tip
  If you want to save the output to a text file for easier sharing, you can redirect the output like this:
  Terminal window
  firefox &> firefox-log.txt
  Remember to press CTRL + C to terminate the process after it fails to start so the terminal writes the output to the file.

Check the latest updated packages in pacman.

To get a list of the most recently updated packages on your system, you can use the following command:

grep "\[ALPM\] upgraded" /var/log/pacman.log | tail -n 50

Keybinds for navigating in journalctl and dmesg

Most common Keybinds to navigate through the logs when less is or human readable mode is being used:

Arrow Keys: to move up and down line by line.

Page Down & Page Up or Ctrl + A/D : to scroll down or up one page at a time.

j & k: to move down or up line by line (similar to Vim).

g or Home: to jump to the beginning of the log.

Shift + G or End: to jump to the end of the log.

Using journalctl to gather system logs

The journalctl command is an extremely useful tool for viewing system logs. Here are some of the most common and useful command combinations.

Basic usage and common examples

View the entire log (from oldest to newest):

journalctl

View logs from the current boot only:

journalctl -b

Security and authentication problems:

journalctl -u sshd -u polkit -b -0 | grep -i "fail\|error\|denied"

Look for authentication failures and security policy denials.

Following logs in Real Time:

journalctl -f

Audio issues from the current boot

journalctl --user -u pipewire -u pipewire-pulse -u wireplumber -b 0

View logs from audio services to troubleshoot sound issues.

Memory (RAM) errors:

journalctl -k | grep -i "memory\|ram"

Look for memory corruption or detection issues.

Bluetooth related issues:

# From the current boot:
journalctl -u bluetooth -b 0
journalctl -u bluetooth -b 0
# From the previous boot:
journalctl -u bluetooth -b -1

Time based Filtering

View logs from the last few minutes/hours:

journalctl --since "10 minutes ago"
journalctl --since "1 hour ago"
journalctl --since "2024-01-15 14:30:00"

View logs from a specific time range:

journalctl --since "09:00" --until "10:00"

Filtering by Priority and Service or Program

Possible priority levels are: debug, info, notice, warning, err, crit, alert, emerg.

Or by using numbers:

0 equals emerg

1 equals alert

2 equals crit

3 equals err

4 equals warning

5 equals notice

6 equals info

and 7 equals debug.

Show only error, critical and emergency messages:

journalctl -p err..emerg

Show logs from a specific system service:

# View logs from the NetworkManager service:
journalctl -u NetworkManager
# View logs from the GDM (GNOME Display Manager) service:
journalctl -u gdm
# View logs from the SDDM (Simple Desktop Display Manager) service:
journalctl -u sddm

Show logs from a specific Process ID (PID):

journalctl _PID=pid
# Example:
journalctl _PID=3344

Show logs from a specific executable:

journalctl path/to/executable
# Example:
journalctl /usr/bin/firefox

Using journalctl to check kernel messages

Basic kernel message viewing:

journalctl -k

Shows all kernel messages from the journal, equivalent to dmesg but from the journal’s perspective.

Current boot kernel messages only:

journalctl -k -b 0

Displays kernel messages from the current boot session only.

Previous boot kernel messages:

journalctl -k -b -1

View kernel messages from the previous boot. Useful for diagnosing boot failures or crashes.

Follow new kernel messages in real time:

journalctl -k -f

Watch kernel messages as they occur, great for monitoring hardware events or driver loading.

Search for specific driver messages:

# Examples:
# GPU related messages:
journalctl -k | grep -i "nvidia\|amd\|intel"
# USB device messages:
journalctl -k | grep -i "usb\|pci"

Time based kernel message filtering:

journalctl -k --since "1 hour ago"
journalctl -k --since "09:00" --until "10:00"

View kernel messages from specific time periods.

Using dmesg for Kernel Messages

The dmesg command displays the kernel ring buffer, which contains messages from the kernel about hardware detection, driver initialization and system events.

Basic Usage and Formatting

View the entire kernel message buffer:

dmesg

View with human-readable timestamps:

dmesg -T

View in a pager for easier reading:

dmesg | less

Filtering by Priority Level

Similar to journalctl, dmesg allows filtering messages by priority level.

Show only errors and critical messages:

dmesg -l err,crit,alert,emerg

Possible priority levels are: debug, info, notice, warning, err, crit, alert, emerg.

Or by using numbers:

0 equals emerg

1 equals alert

2 equals crit

3 equals err

4 equals warning

5 equals notice

6 equals info

and 7 equals debug.

View the most recent kernel messages:

dmesg -w

Search for specific hardware or driver messages:

# Examples:
# To search for USB related messages:
dmesg | grep -i usb | less
# Bluetooth devices:
dmesg | grep -i bluetooth
# NVIDIA related:
dmesg | grep -i nvidia | less
# Devices failing to initialize:
dmesg | grep -i "error\|failed" | less

Common examples for specific issues using dmesg

When a USB device isn’t recognized:

dmesg -w | grep -i usb

Then plug in the device and watch for new messages.

GPU initialization issues:

dmesg | grep -i "nvidia\|amd\|intel\|radeon\|drm\|gpu" | less

WiFi or network adapter issues:

dmesg | grep -i "wlan\|wifi\|network\|firmware" | tail -20

Check for missing firmware loads or driver errors that prevent your wireless card from working.

HDD/SSD detection problems:

dmesg | grep -i "sda\|sdb\|nvme\|scsi\|disk" | head -30

Use this when a storage device isn’t being detected or shows errors during boot.

System freezes or kernel panics:

dmesg -T -l emerg,alert,crit,err | tail -30

Check the most severe kernel messages that occurred before a system crash or freeze.

Memory (RAM) errors:

dmesg | grep -i "memory\|ram"

Look for memory corruption, detection issues, or ECC error reports.

Audio device events:

dmesg | grep -i "audio\|snd\|hda" | grep -i "error\|fail\|card"

Check if your sound card is being detected properly and if drivers are loading correctly.

Kernel module loading failures:

dmesg | grep -i "module\|init" | grep -i "error\|fail"

When specific hardware drivers aren’t loading or are failing to initialize.

Real-time monitoring for hardware events:

dmesg -w -l warn,err,crit,alert,emerg -T

Continuously watch for new important kernel messages while you reproduce an issue.

BIOS/UEFI and firmware issues:

dmesg | grep -i "bios\|uefi\|firmware\|efi"

Check for compatibility issues between your hardware firmware and the Linux kernel.

Installation & Live Environment

Why does the CachyOS live ISO only include KDE Plasma?

We’ve chosen to focus our development and maintenance efforts exclusively on the KDE Plasma desktop environment. This allows us to deliver a more polished, stable, and consistent user experience on our live ISO.

The live environment is primarily intended for installing CachyOS or using cachy-chroot for system recovery. For a safe way to test other desktop environments or window managers, we highly recommend trying them in a virtual machine (VM).

Why does the installer take so long to start after clicking “Launch Installer”?

The installer is not frozen. It is running a necessary background script to prepare your system for installation. This process ensures your system’s keyrings and clock are up-to-date, which helps prevent common installation issues.

View the script on GitHub to have a better understanding of what it does.

Removes old keyring files.
Installs and updates the latest Arch Linux & CachyOS keyring packages.
Initializes and populates the pacman keyring.
Enables network time synchronization.
Checks your system’s boot type (UEFI or BIOS/MBR) to prompt the user to select a bootloader depending on the type.

This is why it can take a bit of time to load the installer.

Why does my installation get stuck at 33%

This happens when the installer is struggling to download packages. It’s usually a sign of a very slow or unstable internet connection. Please check your network connection and try again.

Bootloader Recovery and Btrfs snapshots

Steps to recover your bootloader

Boot into the CachyOS Live ISO.

Open a terminal and chroot into your installed system using the cachy-chroot command.

sudo cachy-chroot

If your system is utilizing BTRFS with our preset say y in the prompt:

Do you want to use CachyOS BTRFS preset to auto mount root subvolume? y
Do you want to mount additional partitions? · yes
Enter the mount point for additional partition (e.g. /boot) type 'skip' to cancel:
# Type /boot for systemd-boot, Limine or rEFInd
# Type /boot/efi for GRUB

Follow the instructions below for your installed bootloader and system type (UEFI or MBR/BIOS).
Reinstall GRUB with the following command:
UEFI
MBR/BIOS
Terminal window
sudo grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=cachyos
Terminal window
sudo grub-install --target=i386-pc /dev/sdX # Replace sdX with your disk e.g. sda
Reinstall systemd-boot with the following command:
Terminal window
sudo bootctl install
Reinstall Limine with the following command:
UEFI
MBR/BIOS
Terminal window
sudo limine-install
Terminal window
sudo limine bios-install /dev/sdX # Replace sdX with your disk e.g. sda
Reinstall rEFInd with the following command:
Terminal window
sudo refind-install

Reinstall the CachyOS kernel:

sudo pacman -Syu linux-cachyos linux-cachyos-headers

Exit from cachy-chroot:
Terminal window
```
exit
```
Reboot your system.

Using a Btrfs snapshot as a rollback point

A BTRFS snapshot appears as an additional boot entry in your bootloader menu and is usually named something like:

10 | 10-30-2025 14:37:10

Example in a screenshot:

You can also use the Btrfs Assistant application to manage your snapshots. It provides a graphical interface to create, delete, and restore snapshots.

Screenshot of Btrfs Assistant:

Package Management & Updates

Pacman Troubleshooting

error: signature is invalid

This error indicates a problem with the cryptographic signature of a package. It is usually caused by an outdated mirror or a broken keyring on your system.

While mirrors often fix themselves after a short while, if the issue persists, you should try one of the following two solutions.

sudo pacman -Syu

sudo cachyos-rate-mirrors

error: 404 Not Found

This error means the package you are trying to install is not available on your current mirror. This usually happens when your local package database is out of sync with the remote repositories.

Solution:

Run the following command to refresh your package database and perform a full system upgrade. This will ensure your system knows about the latest available packages.

sudo pacman -Syu
# Then try to install the package you want again.

error: could not remove

This error occurs when the pacman cache contains files that the system cannot automatically manage. This is a common issue that can be easily fixed.

Solution 1: Use CachyOS Hello.
- The simplest way to fix this is with CachyOS Hello. Open it and go to Apps/Tweaks, then click the Clear package cache button.
Solution 2: Manually remove the cache.
- Run the following command to remove all orphaned packages from the cache.
Terminal window
```
sudo rm -r /var/cache/pacman/pkg/*
```

error: File is corrupted (invalid or corrupted package (PGP signature))

# Example:
:: File /var/cache/pacman/pkg/python-charset-normalizer-3.4.0-1-any.pkg.tar.zst
is corrupted (invalid or corrupted package (PGP signature)).

This error typically indicates a problem with your system’s pacman keyrings, which verify the authenticity of packages. The following commands will reset and re-populate the keyrings to resolve the issue.

sudo rm -rf /etc/pacman.d/gnupg/
sudo pacman-key --init
sudo pacman-key --populate

sudo pacman-key --recv-keys F3B607488DB35A47 --keyserver keyserver.ubuntu.com
sudo pacman-key --lsign-key F3B607488DB35A47

sudo rm -R /var/lib/pacman/sync

error: unable to lock database

This error occurs when another pacman process is already running, which locks the database to prevent corruption. If the previous process crashed or was interrupted, the lock file db.lck might not have been removed.

Solution 1: Use CachyOS Hello
- The simplest way to fix this is with the Remove db lock function in the Apps/Tweaks tab of CachyOS Hello
Solution 2: Remove the lock file manually
- If you prefer not to use CachyOS Hello, you can remove the lock file manually:

sudo rm /var/lib/pacman/db.lck

error: failed retrieving file … Connection timed out

You might see errors like these:

# Example errors:
error: failed retrieving file '...' from ... : Connection timed out
error: failed retrieving file '...' from ... : Couldn't resolve host name
error: failed retrieving file '...' from ... : The requested URL returned error: 526

These errors almost always indicate a problem with your current mirrors. They may be slow, temporarily down, or unreachable from your location.

Solution: The best way to fix this is to update your mirror list with faster and more reliable mirrors.

sudo cachyos-rate-mirrors
# Afterwards, you can update your system with:
sudo pacman -Syu

warning: local is newer than…

This warning appears when a package version on your system is newer than the version available in the official repositories. This can happen if a mirror is out of date or if a package was downgraded in the repositories or if a package was installed from a different source.

Solution: the pacman -Syuu command performs a full system upgrade and allows for downgrades, which will fix the warning by synchronizing your local packages with the repository versions.

sudo pacman -Syuu

error: failed to commit transaction (conflicting files)

This error indicates that pacman is trying to install or update a package that contains files already present on your system from a different source. This is a built-in safety feature to prevent system breakage.

Solution: You can resolve this issue by removing the conflicting files manually. For more information and solutions, please refer to the Arch Wiki.

error: failed to commit transaction (conflicting files)
nvidia-utils: /usr/lib/environment.d/10-gsk.conf exists in filesystem
Errors occurred, no packages were upgraded.
 -> error installing repo packages

To fix this specific example, you would remove the conflicting file and then run your update command again.

sudo rm /usr/lib/environment.d/10-gsk.conf

ERROR: module not found: ‘nvidia’, ‘nvidia_modeset’, …

==> ERROR: module not found: 'nvidia'
==> ERROR: module not found: 'nvidia_modeset'
==> ERROR: module not found: 'nvidia_uvm'
==> ERROR: module not found: 'nvidia_drm'

Two reasons for this error:

Since Early Module Loading is always enabled in chwd, mkinitcpio consistently expects the presence of NVIDIA modules; this error arises when those modules are missing.
You might be missing NVIDIA modules from other installed kernels on your system.

sudo pacman -S nvidia

Specific Software Issues

Discord asks for an update that isn’t available in the repositories.

This happens because Discord uses its own update system, which gets ahead of the official repositories. A new version of the app has been released, but it hasn’t been packaged for our mirrors yet.

In order to get around this issue, follow Arch Wiki’s fix guide.

General questions

What is the interval on which -git packages are updated?

Usually once on Monday, though there may be exceptions.

Do the -bin packages in the CachyOS repositories benefit from the same performance optimizations?

No. The -bin packages are precompiled binaries and do not include the same performance optimizations as the source based packages in the CachyOS repositories.

How to disable the boot loading animation (Plymouth)

To disable the boot loading animation, you need to edit your bootloader configuration and add the following kernel parameters:

plymouth.enable=0 disablehooks=plymouth

Submitting Package Requests to CachyOS

CachyOS offers an extensive list of precompiled AUR Packages, which are commonly used. Users can create requests for AUR packages, which, if approved, are automatically updated by our build server

If you want us to add a package, you can submit a request on GitHub or in the forum.

Security & Best Practices

AUR Safety Practices

The AUR offers a vast selection, but security is paramount. Here’s a concise guide to safe AUR usage for your CachyOS system.

1. Understand the PKGBUILD: It’s the build script. Know its structure, variables (source, pkgname), and functions (build(), package()).
2. Verify Source Links: Always check that source URLs point to official project sites or trusted repositories. Avoid suspicious or personal links.
3. Review Installation Steps: Inspect where files are installed (package() function) and if any commands are unusual or touch sensitive system areas. Check .install scripts too.
4. Research the Maintainer: Look into the maintainer’s history on the AUR for any past security issues or suspicious activity.
5. Check Checksums & PGP: Absolutely crucial! Confirm all checksums (SHA256, BLAKE2b, etc.) match upstream. Use PGP signatures (validpgpkeys) for authenticity when available.
6. Be Cautious with -bin Packages: These use pre-compiled binaries, meaning you can’t inspect the source. Apply maximum scrutiny to their origins and integrity.
7. Read Community Comments: Check the AUR page comments for warnings, issues, or insights from other users.
8. Never Skip Integrity Checks: Using --skipinteg or similar flags bypasses all security checks. Don’t do it.
9. Control Your AUR Helper: Understand how your helper (yay, paru) works. Ensure it shows you the PKGBUILD and its diffs, or build manually with makepkg.
10. Assess Necessity: Before installing, ask if you truly need this AUR package, or if an official repo alternative exists.
11. Keep Your System Updated: Regularly run sudo pacman -Syu to ensure all your system components, including pacman and makepkg, have the latest security patches.

Stay vigilant to keep your Arch-based system secure!

Choosing a GUI Package Manager

While graphical package managers offer convenience, certain ones are known to cause severe issues on rolling-release systems like CachyOS and should be avoided for managing system packages.

Pamac: is known to improperly handle certain package management tasks, such as corrupting system package keyrings. This can lead to PGP signature errors that prevent you from updating your system.
Discover (KDE) & GNOME Software Center: These app stores use the PackageKit backend. While they’re generally safe for managing Flatpaks, using them to install or update system packages is risky. PackageKit-based managers can also be unstable or prone to crashing, which could leave your system in a broken state after a failed transaction.

For maximum stability and reliability, we highly recommend managing system packages through the command line with pacman

If you prefer a graphical interface, GUI front-ends like Octopi or the CachyOS Package Installer are considered as safe alternatives, as they are more direct wrappers for pacman functionality.