# RakuOS support pack

Attach this file to a chat with any AI assistant before asking for help with RakuOS. Generated 2026-10-28, pages fingerprint bda7e95c87cd. Full documentation: https://rakuos.org/ai

---

# Start here: helping a RakuOS user

RakuOS is a Fedora desktop (Fedora 44 on the stable channel, Fedora 45 on staging) shipped as a bootc image. The base system in `/usr` is read-only and replaced whole by image updates; packages the user installs with `rum` or the Software Center live in a persistent overlay on top of it. Fedora Workstation (`dnf`) and Fedora Atomic (`rpm-ostree`) advice is often wrong here, so follow the rules below and translate generic advice before giving it.

Details: [How RakuOS works](https://rakuos.org/ai/01-architecture), [repo map](https://rakuos.org/ai/repo-map), [how RakuOS differs from Fedora](https://rakuos.org/ai/components/fedora-differences). Components: [rum](https://rakuos.org/ai/components/rum), [overlay (rakuos-core)](https://rakuos.org/ai/components/rakuos-core), [Software Center](https://rakuos.org/ai/components/rakuos-software), [RakuOS System](https://rakuos.org/ai/components/rakuos-system), [installer](https://rakuos.org/ai/components/rakuos-installer), [kernel modules and Secure Boot](https://rakuos.org/ai/components/kernel-modules-secure-boot). As of 2026-10-15.

## What RakuOS is

- Editions: KDE, GNOME, COSMIC, niri and Hyprland, each with an install ISO (Hyprland's since 2026-10-28); the gamescope (Steam Gaming Mode) image exists but has no ISO, so a system gets it only by switching an installed system to its image. Channels: `latest` (stable, Fedora 44) and `staging` (Fedora 45). Behavior differs between them in places; the pages say where.
- Images: `quay.io/rakuos/rakuos-<edition>[-nvidia|-nvidia-legacy][-v3|-v4]:<channel>`, signed, updated with `bootc`. `-nvidia-legacy` carries the 580xx driver for Maxwell/Pascal/Volta GPUs.
- Packages: `rum`, RakuOS's own package manager. `dnf` and `dnf5` are shims that run rum. There is no rpm-ostree.
- The overlay: `/var/lib/rakuos/overlay/upper`, mounted on `/usr` at boot. The user's packages are listed in `/var/lib/rakuos/packages.list`, and the overlay can be rebuilt from that list.
- Security: AppArmor. SELinux is not installed and not built into the kernel. The kernel boots with `lockdown=integrity` and `module.sig_enforce=1`: only kernel modules signed by RakuOS load. RakuOS prebuilds and signs its out-of-tree modules (NVIDIA, Broadcom Wi-Fi, Xbox controllers, wheels, …); nothing is compiled or signed on the user's machine.
- Third-party repos: Terra and RPM Fusion are both disabled by default on both channels; images from 2026-10-17 on turned RPM Fusion off on existing installs too, so users who relied on it must turn it back on. The welcome app's Third-Party Repositories page has an RPM Fusion and a Terra switch.
- Anti-cheat: `rakuos eac-check` and the RakuOS System app's Anti-Cheat button check Easy Anti-Cheat Linux v2's requirements.
- User documentation: https://rakuos.org/documentation has plain how-to pages for users (installing, software, updates, drivers, Secure Boot, dual boot, rescue mode, troubleshooting). Link the matching page when it covers the user's question; these AI pages stay the detailed reference.
- `sudo` is sudo-rs, the core utilities are uutils, `ls` is lsd and `cat` is bat (system-wide, not aliases); the GNU versions are available as `gnu_sudo`, `gnu_ls`, `gnu_cat` and so on. On a terminal `cat` shows a framed view with line numbers and opens a pager for long files (press `q`); for text to paste, use `gnu_cat` or the `grep` commands below.

## The support contract

1. **Identify the system first.** Never assume the edition, channel or version. Have the user run the read-only block in [diagnostics](https://rakuos.org/ai/troubleshooting/diagnostics). The short form:

   ```bash
   grep -E '^(PRETTY_NAME|VERSION_ID|VARIANT_ID)=' /etc/os-release   # read-only: VARIANT_ID = edition, plus -staging on staging
   sudo bootc status     # read-only: booted and rollback image, channel tag, version date
   uname -r              # read-only: kernel
   rum paths             # read-only: should say "mode: split (RakuOS overlay)"
   ```

2. **Find the owning component** in the [repo map](https://rakuos.org/ai/repo-map) before proposing a fix.
3. **Use RakuOS tools.** rum or the Software Center for RPM packages, `bootc` for image updates, rollback and switching, Flatpak or Distrobox for isolation. Translate Fedora or Silverblue advice into these, or explain why it does not apply.
4. **Never suggest anything on the "Do not" list** below.
5. **Read-only first.** Before any command that changes the system, say what it changes, how to undo it and whether a reboot is needed. Mention `sudo bootc rollback` before risky steps.
6. **Check [known issues](https://rakuos.org/ai/known-issues) first.** If the problem is known, give the workaround and the tracker link.
7. **New bug? Stop and help file it.** When the code is wrong rather than the user's setup, fill in the bug template from [bug reporting](https://rakuos.org/ai/bug-reporting): the right project from the repo map, redacted logs, every command already run. Have the user confirm each detail before filing at rakuos.org/bugs.
8. **When unsure, say so.** Point to the forum (rakuos.org/forum), Matrix (matrix.rakuos.org) or Discord.

## Do not

| Do not | Why | Do this instead |
|---|---|---|
| Suggest `rpm-ostree install`, `rpm-ostree upgrade` or any `rpm-ostree` command | rpm-ostree is not installed | `sudo rum install <pkg>` for RPMs; `sudo rum system-upgrade` or `sudo bootc upgrade` for updates |
| Treat `dnf` as real dnf, e.g. dnf plugins, `dnf system-upgrade download --releasever`, `dnf offline-upgrade` | `dnf` runs rum; those features do not exist or are refused on an installed system | Use rum's own commands; a new Fedora release arrives as a new image through `bootc` |
| Suggest `rum list --installed` or `dnf list --installed` | rum has no `--installed`; it rejects the flag as an unknown argument (the dnf shim only translates the keyword form `dnf list installed`) | `rum list` shows the overlay packages (what the user installed); `rum list --base` shows the image's packages; `rum origin <pkg>` says which one a package is |
| Check whether or where a package is installed with `rpm -q` or `rpm -qa` | rpm mixes the image's and the overlay's packages, so it can't say where a package came from | `rum list --base \| grep <name>` (in the image) and `rum list \| grep <name>` (installed into the overlay); `rum origin <pkg>` for one package. `rpm -V <pkg>` is still the way to check a package's files |
| Say `rum upgrade` updates the system | It upgrades only overlay packages, never the base image | `sudo rum system-upgrade` (packages, Flatpaks and image), or the Software Center's Updates page, then reboot |
| Assume Terra or RPM Fusion is enabled | Terra and RPM Fusion are disabled by default on both channels | Check with `rum repolist --all`; enable only if the user wants it, in the welcome app's Third-Party Repositories page or with `sudo rum config-manager --set-enabled terra` / `'rpmfusion-*'` (undo: `--set-disabled`) |
| Write or edit `.repo` files in `/etc/yum.repos.d` or `/usr/share/…/repos.d` by hand | rum keeps repo files in its own dirs (`/etc/rum.repos.d` for the user's, `/usr/share/rum/repos.d` from packages); files under `/usr/share` belong to packages | `sudo rum config-manager --set-enabled/--set-disabled <id>`, `sudo rum config-manager addrepo --from-repofile=<url>`, `sudo rum copr enable` |
| Delete or mask `/usr/share/rum/repos.override.d/20-rakuos.repo` (e.g. an empty `20-rakuos.repo` in `/etc/rum/repos.override.d`), or try to get around its excludes, to install Fedora's `goverlay`, RPM Fusion's NVIDIA packages or steam, or Terra's AppArmor/scx packages | Those excludes keep other repos' builds from replacing RakuOS's own (the NVIDIA driver, GOverlay, AppArmor, sched_ext); masking the file drops all of them at once | Use the RakuOS packages; for the NVIDIA driver, an `-nvidia` or `-nvidia-legacy` image. Own extra overrides go in a new file such as `/etc/rum/repos.override.d/99-local.repo`. See [rum](https://rakuos.org/ai/components/rum#repo-overrides) |
| Suggest installing `akmod-*` or `dkms-*` packages, `akmods`, `dkms autoinstall`, building a module with `make`, or `rakuos setup-nvidia` / `setup-nvidia-legacy` | A module built on the machine is unsigned and the kernel refuses it; `setup-nvidia*` installs DKMS packages | The image's `rakuos-kmod-*` modules; an `-nvidia` or `-nvidia-legacy` image for NVIDIA; `rakuos-kmod-VirtualBox…` for VirtualBox. Missing module: ask RakuOS (Discord or rakuos.org/bugs). See [Kernel modules and Secure Boot](https://rakuos.org/ai/components/kernel-modules-secure-boot) |
| Suggest generating a signing key, `mokutil --import` of a self-made key, `sign-file`, or DKMS/akmods signing settings | RakuOS enrolls only its own key; `rakuos enroll-secureboot-key` deletes locally generated MOKs, and they fail the anti-cheat check | Use RakuOS-signed modules as above |
| Say `rakuos enroll-secureboot-key` removes Microsoft's or other distributions' keys, or warn that it breaks Windows or Linux dual boot | It removes only unknown MOKs (machine-made keys: self-made, akmods/DKMS, the old per-machine RakuOS key) and keeps Microsoft, Linux and BSD vendor keys; it never touches the firmware's `db`/`KEK` | Run it and read its `KEEP:`/`Removing:` lines; nothing is deleted until **Delete MOK** is confirmed at the next boot |
| Suggest disabling Secure Boot, or adding `module.sig_enforce=0`, `lockdown=none` or `iommu=pt`, as a fix | These are deliberate security settings and Easy Anti-Cheat requirements; RakuOS System has no switch for them | Find the RakuOS-signed alternative; for anti-cheat problems run `rakuos eac-check`. One exception: hardware the IOMMU breaks (e.g. a TPM no longer found on an older Intel laptop) gets `intel_iommu=off` in RakuOS System after a one-boot test; see [TPM not found](https://rakuos.org/ai/troubleshooting/tpm-missing-after-iommu) |
| Suggest `setenforce`, `restorecon`, `chcon`, `semanage`, `audit2allow`, or "disable SELinux" | SELinux is not present; these do nothing useful | `auditd` runs, so denials are in the audit log: `sudo ausearch -m AVC -ts today` (read-only). On RakuOS an `AVC` record with an `apparmor="DENIED"` field is AppArmor, not SELinux; report it |
| Suggest disabling AppArmor or `apparmor.service` as a fix | It is the system's only mandatory access control | Collect the denial lines and file a bug against the owning project |
| Install packages with `rpm -i`, `rpm -U` or `rpm -e` | rum's overlay database would not record them, and the next image update overwrites the package view rpm uses | `sudo rum install ./file.rpm`, `sudo rum remove <pkg>` |
| Copy files into `/usr` by hand, or run installers (`curl … \| sh`, `make install`) that write to `/usr` | Files land in the overlay untracked and can hide newer files from later images | Flatpak, Distrobox, `~/.local`, or `/usr/local` (which is `/var/usrlocal`, outside the overlay) |
| Delete files under `/var/lib/rakuos/overlay/upper` | It holds every overlay package; manual edits break rum's records | `sudo rum remove <pkg>`, `sudo rum restore-base-files <pkg> --dry-run` then without `--dry-run`, or `sudo rakuos reset-overlay --soft` |
| Run `sudo rakuos reset-overlay --confirm` as a first step | It forgets every installed RPM | Try targeted fixes first, then `--soft`; back up `/var/lib/rakuos/packages.list` before either |
| Assume GNU coreutils or GNU sudo behavior | They are uutils, lsd (`ls`), bat (`cat`) and sudo-rs | If a GNU-only option fails, use the `gnu_*` binary (e.g. `gnu_ls`) |
| Suggest `grub2-mkconfig`, `update-grub`, `grub2-install`, or editing `/boot/grub2/grub.cfg`, `os-prober.cfg` or the marked RakuOS blocks in `user.cfg`/`custom.cfg` | `grub.cfg` is bootupd's static config; RakuOS's scripts own those files and blocks and rewrite them | Other OSes missing: `sudo /usr/libexec/rakuos/os-entries` (`--dry-run` first). The user's own GRUB additions go outside the marked blocks in `/boot/grub2/custom.cfg`. See [rakuos-core](https://rakuos.org/ai/components/rakuos-core#boot-menu-and-bootloader) |
| Suggest unmasking `bootloader-update.service` or running `bootupctl update` | It is masked on purpose; `rakuos-bootloader-update` does that job with RakuOS's checks | `journalctl -b -u rakuos-bootloader-update`; `sudo /usr/libexec/rakuos/bootloader-update --dry-run` |
| Tell a user stuck at boot to reinstall | Images from 2026-10-16 on have a **RakuOS rescue** GRUB submenu that boots without the overlay | [Stuck at boot after a reset](https://rakuos.org/ai/troubleshooting/stuck-at-boot-overlay) or [System won't boot after an update](https://rakuos.org/ai/troubleshooting/boot-stuck-after-update) |
| Force a `rakuos-kmod-*` update rum doesn't offer (`rum install <newer NEVRA>`, downloading the RPM), or upgrade a kmod's `*-kmod-common`/firmware on its own | A kmod update that isn't offered is built for a kernel the system isn't running yet, and its dependencies are held to match the installed kmod; forcing either leaves a module that doesn't load | Wait for the image update: `sudo rum system-upgrade` or the Software Center runs `rum kmod-upgrade` for the new kernel first. Preview with `sudo rum kmod-upgrade --dry-run` |
| Expect automatic updates | No update timer is enabled by default | Tell the user to update from the Software Center or with `sudo rum system-upgrade` |


---

# How RakuOS works

RakuOS is a Fedora system (Fedora 44 on the stable channel, Fedora 45 on staging) shipped as a signed bootc container image. The image's `/usr` is read-only; packages the user installs with `rum` or the Software Center go into a persistent overlay on top of it, stored in `/var/lib/rakuos/overlay/upper`. Image updates, rollbacks and edition switches go through `bootc`, and at each boot the initrd decides whether the overlay can be kept as it is, needs its package database view refreshed, or must be rebuilt from the user's package list.

As of 2026-10-15, image v2/v3/v4. Packages from their `main` branches (built for both releases); images from `main` (stable) and `staging`, with differences marked.

## The pieces

| Piece | What it is | Where |
|---|---|---|
| Base image | `quay.io/rakuos/rakuos-<edition>[-nvidia\|-nvidia-legacy][-v3\|-v4]:<channel>` | the booted ostree deployment's `/usr` |
| Overlay | overlayfs mounted on `/usr`, lower = image, upper = user's packages | `/var/lib/rakuos/overlay/{upper,work}` |
| Package list | names the user installed; the overlay is rebuilt from it | `/var/lib/rakuos/packages.list`, local RPMs in `packages-rpm.list` and `local-rpms/` |
| Overlay package database | rum's record of overlay packages, separate from the base's | `/var/lib/rakuos/rum-rpmdb` |
| Markers | `current-deploy` (last `ostree=` boot argument), `os-version`, `de-name`, `overlay.state`, `overlay.dirty` | `/var/lib/rakuos/` |
| rum | the package manager; `dnf` and `dnf5` are shims that run it | `/usr/bin/rum`, `/usr/bin/dnf` |
| Repo files | user's repos and changes; repo files from packages | `/etc/rum.repos.d`; `/usr/share/rum/repos.d` (rum also reads `/etc/yum.repos.d` and `/usr/share/dnf5/repos.d`) |

Editions: `kde`, `gnome`, `cosmic`, `niri`, `hyprland`, `gamescope`. KDE, GNOME, COSMIC, niri and Hyprland (plus a minimal image) have install ISOs; gamescope is reached by switching an installed system. Channels: `latest` (stable, built from `main`, Fedora 44) and `staging` (built from `staging`, Fedora 45). Every build also gets a dated tag: `latest.YYYYMMDD` or `staging.YYYYMMDD`. The suffix `-v3` or `-v4` selects a kernel and repos built for that x86-64 level; no suffix is v2. `-nvidia` adds the NVIDIA driver; `-nvidia-legacy` adds the 580xx driver for Maxwell, Pascal and Volta GPUs (staging only as of 2026-10-15). Each image carries the label `org.rakuos.fedora.version` with its Fedora release.

To tell which one a machine runs:

```bash
cat /etc/os-release      # read-only: VARIANT_ID is the edition, with -staging on the staging channel (e.g. cosmic-staging)
sudo bootc status        # read-only: booted and rollback image refs (example from a customized test machine: quay.io/rakuos/rakuos-cosmic-v4:staging, version staging.20261013)
uname -r                 # read-only: kernel release, e.g. 7.3.0-rakuos.2.v4.staging.fc45.x86_64 (kernel-rakuos-v4-staging)
```

`/etc/os-release` does not record the x86-64 level or NVIDIA; read those from the image name in `bootc status`. Its `VERSION_ID` is the Fedora release (44 or 45).

## Lifecycle

```mermaid
flowchart TD
    ISO[Live ISO<br/>Fedora kernel, overlay units masked] -->|rakuos-installer:<br/>bootc install to-filesystem| DISK[Installed system<br/>tracks the ISO's image ref]
    DISK --> BOOT
    subgraph BOOT[Every boot]
        I[initrd: rakuos-overlay-mount.service] -->|checks markers| R{Reset or change?}
        R -->|soft or hard reset queued,<br/>VERSION_ID or desktop changed| W[wipe /var/lib/rakuos state]
        R -->|new deployment| S[reseed rpmdb view]
        R -->|nothing| M[mount overlay on /usr]
        W --> M
        S --> M
        M --> Y[rakuos-overlay-sync.service<br/>before the login screen]
        Y -->|state missing or dirty| RI[rum install packages.list]
    end
    BOOT --> USE[Session: rum, Software Center,<br/>Flatpak, Distrobox, AppImages]
    USE -->|rum system-upgrade,<br/>Software Center update| UP[bootc upgrade stages new image]
    USE -->|bootc rollback| RB[previous deployment queued]
    USE -->|bootc switch| SW[other edition or channel staged]
    USE -->|rakuos reset-overlay| RS[reset marker set]
    UP --> BOOT
    RB --> BOOT
    SW --> BOOT
    RS --> BOOT
```

## 1. Installing from the ISO

The live ISO is built by RakuForge from the edition image. Its live session boots Fedora's signed kernel, not kernel-rakuos, and masks `rakuos-overlay-mount.service` and `rakuos-overlay-sync.service`. Boot menu entries: the default, "Basic Graphics Mode" (adds `nomodeset`) and "Text-Mode Installer".

The installer (`rakuos-installer`, frontends GTK, Qt, COSMIC and text) copies the image baked into the ISO to disk and runs `bootc install to-filesystem --target-imgref <that image>`. The installed system therefore follows the same image name and channel as the ISO; there is no edition or channel choice in the installer. Defaults: Btrfs with subvolumes `@`, `@home` and `@snapshots`, GRUB, optional LUKS2 encryption unlocked by TPM2. The disk must be at least 40 GiB.

The ISOs install the stable (`latest`) image. If the machine boots with UEFI and Secure Boot on, the installer queues one key for enrollment: the RakuOS certificate `/usr/share/rakuos/sb_pubkey.der`. (Installers before 2026-10-15 also queued a per-machine module signing key; `sudo rakuos enroll-secureboot-key` removes it.)

## 2. First boot

1. With Secure Boot on, MOK Manager (a blue screen) appears before RakuOS starts. Choose Enroll MOK, then Continue, type the password `rakuos`, then Reboot. If this was skipped, run `sudo rakuos enroll-secureboot-key` later and repeat the steps at the next boot. The RakuOS kernel is signed with this key, so with Secure Boot on it boots only once the key is enrolled. `enroll-secureboot-key` also queues every enrolled MOK that isn't a well-known vendor key for deletion, such as the per-machine key earlier installers created (`CN=RakuOS Machine Module Signing Key`); MOK Manager then offers Delete MOK too, completed the same way.
2. In the initrd, `rakuos-overlay-mount.service` (dracut module `90rakuos-overlay`, after `ostree-prepare-root.service`) creates the overlay directories. Because `packages.list` does not exist yet, it copies the image's prebaked overlay from `/usr/share/factory/var/lib/rakuos/` and mounts the overlay. Its messages start with `RakuOS overlay:`.
3. Before the login screen, `rakuos-overlay-sync.service` finds the prebaked state and finalizes it: "Finalizing initial package overlay..." on the boot splash. Each edition's prebaked list holds only Firefox.
4. At login, the welcome app (`rakuos-welcome`) offers a Third-Party Repositories page (RPM Fusion and Terra switches, both off) and a set of apps. It keeps opening at each login until the user clicks Finish. There is no Drivers page any more.

## 3. Every later boot

`rakuos-overlay-mount` runs these checks in the initrd, in order:

| Check | Result |
|---|---|
| `VERSION_ID` in the image differs from `/var/lib/rakuos/os-version` | soft reset queued (Fedora release changed) |
| `/usr/share/rakuos/de-name` differs from `/var/lib/rakuos/de-name` | soft reset queued (edition changed) |
| whiteouts hide a whole top-level `/usr` directory | soft reset queued, logged `CRITICAL — …` |
| hard or soft reset queued | state wiped, see [Resetting the overlay](#7-resetting-the-overlay) |
| otherwise, `ostree=` boot argument differs from `/var/lib/rakuos/current-deploy` | reseed: the base's `/usr/share/rpm` and `packages.toml` are copied into the upper dir |

Then it mounts the overlay with `lowerdir=/sysroot/usr` and the upper and work dirs, unless the upper dir is empty, in which case `rakuos-overlay-sync` mounts it later.

`rakuos-overlay-sync.service` then acts on the state:

- prebaked state: finalize, no download;
- overlay empty or `overlay.state` missing: `rum install` of everything in `packages.list`;
- `overlay.dirty` present: reinstall `packages.list`, then reboot once;
- otherwise: nothing.

Installs need the network. Without it the boot splash shows "Connect to the internet, then reboot to finish installing default applications." and the install waits for the next boot. Logs:

```bash
journalctl -b -u rakuos-overlay-sync.service   # read-only
journalctl -b | grep 'RakuOS overlay'          # read-only: initrd messages
```

Boot menu upkeep (images from 2026-10-16 on): `rakuos-bootloader-update` updates shim and GRUB on the ESP from the booted image, `rakuos-rescue-entries` keeps the **RakuOS rescue** GRUB submenu current, and 2 minutes after the first boot of a new deployment `rakuos-os-entries` refreshes the entries for other operating systems. Details: [rakuos-core](https://rakuos.org/ai/components/rakuos-core#boot-menu-and-bootloader).

## 4. Installing software

| Method | Where it goes | Command |
|---|---|---|
| rum | overlay (`/usr`), recorded in `packages.list` and `rum-rpmdb` | `sudo rum install <pkg>` |
| Software Center ("Add/Remove Software") | same as rum; it runs rum | GUI |
| Flatpak | `/var/lib/flatpak` or `~/.local/share/flatpak` | `flatpak install <app-id>` |
| Distrobox | a podman container in the user's home | `distrobox create --name box --image fedora:44` |
| Local RPM | overlay; file kept in `/var/lib/rakuos/local-rpms/` | `sudo rum install ./file.rpm` |
| AppImage | the user's files; the Software Center can register it | GUI, or `chmod +x` and run |

```bash
sudo rum install <pkg>   # changes system: adds <pkg> to the overlay, takes effect immediately, no reboot. Undo: sudo rum remove <pkg>
rum paths                # read-only: should print "mode: split (RakuOS overlay)"
rum origin <pkg>         # read-only: Base, Overlay, Installed or NotInstalled
```

Rules rum follows on an installed system:

- It never modifies the base image. Installing a package the image already provides does nothing ("already installed (base image or overlay) — skipping"); upgrading one prints "provided by the base image … skipping".
- A local `.rpm` is installed from its own header without dependency resolution; missing dependencies must be installed separately. For a missing library named in an error, `rum provides '<library>()(64bit)'` (read-only, exact capability name) shows which package to install.
- Software that installs into `/opt` is moved to `/usr/lib/opt/<name>`, and `/opt/<name>` becomes a symlink to it, because `/opt` itself is `/var/opt`.
- `/usr/local` is `/var/usrlocal` and is not part of the overlay.

Third-party repos: Terra and RPM Fusion are installed but disabled by default on both channels (RPM Fusion's NVIDIA packages and steam are always excluded, as are Terra's AppArmor and scx packages and Fedora's goverlay; from 2026-10-22 these excludes come from the rum repo override `/usr/share/rum/repos.override.d/20-rakuos.repo`, see [rum](https://rakuos.org/ai/components/rum#repo-overrides)). Images from 2026-10-17 on turned RPM Fusion off on existing installs too. To use them, the welcome app's Third-Party Repositories page, or:

```bash
rum repolist --all                                    # read-only: shows which repos are enabled
sudo rum config-manager --set-enabled terra           # changes system: enables Terra (writes a copy of its repo file to /etc/rum.repos.d). Undo: --set-disabled terra, which removes the copy again. No reboot.
sudo rum config-manager --set-enabled 'rpmfusion-*'   # changes system: enables RPM Fusion's package repos (a wildcard skips -source, -debuginfo and -testing repos). Undo: --set-disabled 'rpmfusion-*'. No reboot.
```

rum reads repo files from `/etc/rum.repos.d` (the user's repos and changes), `/etc/yum.repos.d`, `/usr/share/rum/repos.d` (from packages) and `/usr/share/dnf5/repos.d`, in that order; a file in an earlier dir hides one with the same name in a later dir. Packages' repo files are installed into `/usr/share/rum/repos.d`. See [rum](https://rakuos.org/ai/components/rum#repo-files). Options from repo override files (`/etc/rum/repos.override.d`, `/usr/share/rum/repos.override.d`, and dnf5's two) are applied on top; see [Repo overrides](https://rakuos.org/ai/components/rum#repo-overrides).

### Kernel modules and Secure Boot

The kernel boots with `lockdown=integrity` and `module.sig_enforce=1` (from `/usr/lib/bootc/kargs.d/10-rakuos.toml`), so it loads only signed modules. RakuOS builds and signs its out-of-tree modules: images ship them as `rakuos-kmod-<name>` packages (`-staging` on staging; NVIDIA in `-nvidia` images, Broadcom `wl`, `v4l2loopback`, Xbox controllers, racing wheels and others). An `akmod-*` or `dkms-*` package installed with rum builds an unsigned module that will not load; `rakuos setup-nvidia` does the same. VirtualBox and OpenRazer users add `rakuos-kmod-VirtualBox` or `rakuos-kmod-openrazer` (with the image's suffix) to the overlay. See [Kernel modules and Secure Boot](https://rakuos.org/ai/components/kernel-modules-secure-boot) and [A driver won't load](https://rakuos.org/ai/troubleshooting/kernel-module-wont-load).

The same settings, plus IOMMU without passthrough and kexec disabled, are what Easy Anti-Cheat Linux v2 requires. `rakuos eac-check` (or the Anti-Cheat button in RakuOS System) checks them; the RakuOS key is not yet on Epic's list of well-known keys, so the best result today is a yellow "Suggestions". See [Anti-cheat not ready](https://rakuos.org/ai/troubleshooting/anti-cheat-not-ready).

## 5. Updating

Nothing updates automatically: no update timer is enabled by default. The update paths:

| Command or app | Overlay packages | Flatpaks | Base image |
|---|---|---|---|
| `sudo rum upgrade` | yes | no | no |
| `sudo rum system-upgrade` | yes (on a Fedora release change: soft reset instead) | yes | `bootc upgrade` |
| `sudo rakuos upgrade` (used by the apps; not in `rakuos --help`) | yes | yes | `bootc upgrade` |
| `sudo rakuos system-upgrade` (same) | no | no | `bootc upgrade` |
| `sudo bootc upgrade` | no | no | yes |
| Software Center, Updates page | yes | yes | yes, through `rakuos-update upgrade-image` |

```bash
sudo rum system-upgrade   # changes system: upgrades overlay packages and Flatpaks, then stages the newest image of the current channel. Reboot to use the new image. Undo after reboot: sudo bootc rollback
```

For a normal full update, use the Software Center's Updates page or `sudo rum system-upgrade`, then reboot.

`bootc upgrade` stages the new image; the running system does not change until the reboot. At shutdown, right after `ostree-finalize-staged` writes the new deployment, `rakuos-grub-theme.service` installs its GRUB theme and rewrites the rescue entries. The shell alias `update` runs `sudo rum system-upgrade`.

When an update moves to a newer Fedora release (the new image's `org.rakuos.fedora.version` label is higher than `VERSION_ID`), the Software Center and `sudo rum system-upgrade` first run `/usr/libexec/rakuos/rakuos-reset-overlay --soft --releasever <N>` (the same as `sudo rakuos reset-overlay --soft --releasever <N>`), which downloads the overlay packages for the new release; if that fails, the image update is not started. A plain `sudo bootc upgrade`, `sudo bootc switch` or a switch in the RakuOS System app skips this step, and the initrd queues the soft reset itself on the first boot of the new release, reinstalling from the network.

## 6. Reseed, rollback and switching

After a reboot into a different deployment (update, rollback or switch), the initrd reseeds: it copies the new base's package database view into the overlay so rum sees the new base. Files in the overlay are kept as they are.

```bash
sudo bootc rollback   # changes system: makes the previous deployment the default for the next boot. Reboot required. Undo: sudo bootc rollback again
```

- Same Fedora release and edition: overlay packages stay installed.
- Different Fedora release or edition: the overlay is soft-reset and reinstalled from `packages.list` (network needed). Stable (44) and staging (45) are different releases, so switching channel counts too.
- The RakuOS System app's Deployments page can also pin a deployment (`ostree admin pin`) or pick which one boots next (`ostree admin set-default`).

Switching edition, channel, x86-64 level or NVIDIA variant (Standard, Nvidia, Nvidia Legacy) uses the RakuOS System app (System page) or:

```bash
sudo bootc switch quay.io/rakuos/rakuos-kde-v4:latest   # changes system: stages a different image. Reboot required. Undo: sudo bootc rollback. A different edition or Fedora release soft-resets the overlay on first boot.
```

## 7. Resetting the overlay

Try the soft reset first. The hard reset cannot be undone: it forgets every RPM the user installed. Back up the package list before either one.

```bash
cp /var/lib/rakuos/packages.list ~/packages.list.bak   # changes only the home dir: backup of the installed-package list
sudo rakuos reset-overlay --soft      # changes system: at next boot wipes the overlay and reinstalls everything in packages.list. Reboot required. Cannot be cancelled after the reboot.
sudo rakuos reset-overlay --confirm   # changes system, destructive: at next boot wipes the overlay AND packages.list, returning to the image's defaults. Reboot required. Reinstall from the backup afterwards with sudo rum install.
```

- Soft reset first downloads every package in `packages.list`. If that fails it prints "Soft reset aborted — nothing has been changed." Keeps `packages.list`, local RPMs and the markers. `--releasever N` downloads from Fedora N's repos, for a move to an image built on Fedora N.
- Hard reset removes all of `/var/lib/rakuos` except a few markers, then restores the image's prebaked overlay.
- Both clear `/var/cache/libdnf5` and remove `/opt` symlinks into `/usr/lib/opt`.
- Neither touches `/etc`, `/home`, Flatpaks or the rest of `/var`.
- The RakuOS System app's Overlay page runs the same commands.
- If the reinstall after a reset fails at every boot, boot an entry from the **RakuOS rescue** GRUB submenu (no overlay, text login) and reset from there: [Stuck at boot after a reset](https://rakuos.org/ai/troubleshooting/stuck-at-boot-overlay).


---

# Diagnostics

Run this read-only block before giving any advice. It avoids `cat`, which on RakuOS is bat: on a terminal it adds a frame and line numbers and opens a pager for long output (press `q` to leave it); use `gnu_cat` when plain file contents are needed. It identifies the edition, channel, image build, kernel and overlay state, and shows the boot-time overlay log. Nothing in it changes the system.

As of 2026-10-15. Example output on this page comes from a customized COSMIC staging v4 test machine taken on 2026-10-14, while staging was still Fedora 44; staging is now Fedora 45, and values on a user's machine will differ.

## The block

```bash
grep -E '^(PRETTY_NAME|VERSION_ID|VARIANT_ID)=' /etc/os-release   # read-only
sudo bootc status                                                 # read-only
uname -r                                                          # read-only
rum paths                                                         # read-only
findmnt /usr                                                      # read-only
journalctl -b -u 'rakuos-*' --no-pager | tail -n 60               # read-only
journalctl -b -p err --no-pager | tail -n 60                      # read-only: errors from any service this boot
```

When the problem involves a specific package, add:

```bash
rum origin <pkg>                                            # read-only
rum list --base | grep <pkg>                                # read-only: in the base image?
rum list | grep <pkg>                                       # read-only: installed into the overlay?
rpm -V <pkg>                                                # read-only: lists missing or changed files
```

When a driver, kernel module or Secure Boot is involved, add:

```bash
gnu_cat /proc/cmdline                                       # read-only: kernel arguments in effect
mokutil --sb-state                                          # read-only: Secure Boot on or off
rum list --base | grep rakuos-kmod                          # read-only: RakuOS-signed module packages in the image (none on stable images before 2026-10-17)
rum list | grep rakuos-kmod                                 # read-only: opt-in signed modules installed into the overlay
rum list | grep -i -E 'akmod|dkms|kmod|nvidia'              # read-only: module or driver packages in the overlay
journalctl -k -b | grep -i -E 'rejected|verification failed'   # read-only: modules the kernel refused
```

When a game's anti-cheat is involved, add `sudo rakuos eac-check` (read-only).

When an app is blocked or fails with "permission denied", add:

```bash
sudo ausearch -m AVC -ts today | grep apparmor              # read-only
```

## Reading the output

### os-release

```
PRETTY_NAME="RakuOS COSMIC Staging"
VERSION_ID=44
VARIANT_ID=cosmic-staging
```

- `VARIANT_ID` is the edition: `kde`, `gnome`, `cosmic`, `niri`, `hyprland`, `gamescope`, or `rakuos` for the plain base. A `-staging` suffix means the staging channel; no suffix means stable (`latest`).
- `VERSION_ID` is the Fedora release: 44 on stable, 45 on staging as of 2026-10-15.
- The x86-64 level and NVIDIA are not here; read them from the image name below.

### sudo bootc status

```
spec:
  image:
    image: quay.io/rakuos/rakuos-cosmic-v4:staging
status:
  staged: null
  booted:
    image:
      image:
        image: quay.io/rakuos/rakuos-cosmic-v4:staging
      version: staging.20261013
      timestamp: 2026-10-13T20:37:04Z
      imageDigest: sha256:8399…
  rollback:
    …
```

- **Image name**: `quay.io/rakuos/rakuos-<edition>[-nvidia|-nvidia-legacy][-v3|-v4]:<channel>`. `-nvidia` means the NVIDIA image, `-nvidia-legacy` the 580xx NVIDIA image; `-v3`/`-v4` the x86-64 level (none = v2); the tag `latest` is stable, `staging` is staging.
- **booted**: what is running now. **staged**: an update or switch waiting for the next reboot; `null` means none. **rollback**: what `sudo bootc rollback` would return to.
- **version** is `<channel>.<YYYYMMDD>`. Several builds can share one date, so tell deployments apart by `imageDigest`, not by `version`.
- `composefs: null` (in `sudo bootc status --json`) is normal on RakuOS, for booted and rollback entries alike. It is not a fault.
- `usrOverlay: null` is also normal. bootc's own temporary `/usr` overlay is not used; the RakuOS overlay shows up in `findmnt /usr` instead.
- If `bootc status` shows an image that is not under `quay.io/rakuos/`, the user has switched away from RakuOS images; most of this knowledge base then does not apply.

### uname -r

`7.3.0-rakuos.2.v4.staging.fc45.x86_64` is `kernel-rakuos-v4-staging`, build 2, kernel 7.3.0, built for Fedora 45; a stable kernel has no `.staging` (e.g. `7.3.0-rakuos.1.v4.fc44.x86_64`), a gamescope kernel is `kernel-rakuos-deck-…`. A release containing `p03` (for example `7.2.8.p03raku…`) is a retired P03 kernel: update the system before troubleshooting further.

### rum paths

```
mode: split (RakuOS overlay)
base snapshot rpmdb: /usr/share/rpm
overlay rpmdb: /var/lib/rakuos/rum-rpmdb
overlay upperdir: /var/lib/rakuos/overlay/upper
```

`mode: split` is correct on an installed system. `mode: standalone` on an installed system means the overlay is not active; see [Packages won't install or update; rum says standalone mode](https://rakuos.org/ai/troubleshooting/rum-standalone-mode).

### findmnt /usr

Expected: `FSTYPE` `overlay` with `lowerdir=/sysroot/usr` and `upperdir=…/var/lib/rakuos/overlay/upper`. No overlay on `/usr` means overlay packages are not visible.

### journalctl -b -u 'rakuos-*'

A healthy boot after an update looks like:

```
rakuos-overlay-mount: RakuOS overlay: pre-pivot hook starting...
rakuos-overlay-mount: RakuOS overlay: deployment changed (…) — reseeding /usr/share/rpm view from new base...
rakuos-overlay-mount: RakuOS overlay: reseed complete.
rakuos-overlay-mount: RakuOS overlay: mounting persistent overlay over /sysroot/usr...
rakuos-overlay-mount: RakuOS overlay: mounted.
rakuos-base-protect: rakuos-base-protect: watching /var/lib/rakuos/overlay/upper
rakuos-overlay-sync: RakuOS overlay sync: nothing to do.
```

- No `deployment changed` line: the boot used the same deployment as before (normal when nothing was updated).
- `soft reset marker found`, `version change detected`, `DE change detected`: an overlay rebuild ran; `rakuos-overlay-sync` then reinstalls packages (network needed).
- `CRITICAL — …`: whiteouts hid a whole `/usr` directory; a soft reset was queued automatically.
- `RakuOS overlay: FATAL: …` or `RakuOS overlay sync: FATAL — …`: a bug; collect the full log and see [bug reporting](https://rakuos.org/ai/bug-reporting).
- `rakuos-base-protect: BLOCKED …`: something tried to overwrite a base-image file; see [rakuos-core](https://rakuos.org/ai/components/rakuos-core#base-file-protection).
- `bootloader-update: …`, `rescue-entries: …`, `os-entries: …`: boot menu and bootloader upkeep; see [rakuos-core](https://rakuos.org/ai/components/rakuos-core#boot-menu-and-bootloader).

For one unit: `journalctl -b -u rakuos-overlay-sync.service`. If the problem happened before the last reboot, use `-b -1` instead of `-b`.

An update that was staged but isn't running after the reboot (`booted` unchanged, `staged: null`) failed while being written at shutdown; its error is in `journalctl -b -1 -u ostree-finalize-staged.service` and `journalctl -b -u ostree-boot-complete.service`, not in any rpm-ostree log. See [Update not applied after reboot](https://rakuos.org/ai/troubleshooting/update-not-applied-after-reboot).

### rum origin and rpm -V

- `rum origin <pkg>`: `Base` (from the image), `Overlay` (installed by the user), `NotInstalled`.
- `rpm -V <pkg>` lines starting `missing` name files the package should have but the system does not show. For a `Base` package this usually means something in the overlay hides the image's file; see [Package installed but its files are missing](https://rakuos.org/ai/troubleshooting/files-missing-after-update).

### Kernel modules and Secure Boot

- `/proc/cmdline` on a current image contains `lockdown=integrity`, `module.sig_enforce=1`, `intel_iommu=on`, `iommu.passthrough=0`, `iommu.strict=1` and `sysctl.kernel.kexec_load_disabled=1`. Images built before rakuos-settings `65ffdaf` (2026-10-15) lack some of them.
- `Key was rejected by service` from `modprobe`, or `Loading of unsigned module is rejected` in the kernel log: a locally built (akmod/DKMS) module; see [A driver won't load](https://rakuos.org/ai/troubleshooting/kernel-module-wont-load).
- `rakuos eac-check` lines: `[ OK ]`, `[NOTE]`, `[FAIL]`, `[ ?? ]` (needs root); see [Anti-cheat not ready](https://rakuos.org/ai/troubleshooting/anti-cheat-not-ready).

### ausearch

`AVC` records with `apparmor="DENIED"` are AppArmor denials, not SELinux. Note the `profile=`, `operation=` and `name=` fields and include them in a bug report against the project that owns the program.

## Before sharing output

Remove user names, host names, IP and MAC addresses, e-mail addresses and serial numbers. See [bug reporting](https://rakuos.org/ai/bug-reporting#redacting-logs).


---

# Known issues

Open RakuOS bugs that users run into, each with its workaround and tracker link. Check here before troubleshooting; if the problem is listed, give the workaround and the link instead of improvising, and suggest adding details to the existing report rather than filing a new one.

Last checked against https://rakuos.org/bugs on 2026-10-14; entries marked "found in code" were checked against the source on 2026-10-15. Status words are the tracker's. Playbook links give more detail where needed.

## Packages and the overlay

### Package shows as installed but its files are missing after an update

Open, rakuos-base (fix planned in rakuos-core): https://rakuos.org/bugs/b/overlay-whiteouts-hide-base-image-files-after-layered-packages-moved-into-the-base-image-xrdb-fuse-libs-4d54a1a8. Seen with `xrdb` and `fuse-libs` after they moved into the image (`staging.20261003`); `rum reinstall` refuses with "'<pkg>' is provided by the base image … skipping".

```bash
rpm -V <pkg>                                # read-only: "missing" lines confirm it
sudo rum restore-base-files <pkg> --dry-run # read-only in effect: lists the hidden files
sudo rum restore-base-files <pkg>           # changes system: copies them back from the booted image; no reboot
```

If the dry run lists nothing while files are still missing: back up the package list (`cp /var/lib/rakuos/packages.list ~/packages.list.bak`), then `sudo rakuos reset-overlay --soft` (changes system: reinstalls all overlay packages at the next boot; network and reboot needed). Do not delete files in `/var/lib/rakuos/overlay/upper` by hand. [Playbook](https://rakuos.org/ai/troubleshooting/files-missing-after-update).

### Removing Brave, Chromium or another /opt app leaves a broken link

Open, rakuos-rum: https://rakuos.org/bugs/b/when-removing-a-package-that-puts-files-in-usr-lib-opt-brave-chromium-rum-does-not-properly-remove-the-symlink-located-in-opt-965525d1 (duplicate: …-2c2451d4).

- Reinstalling works: current rum clears the stale `/opt/<name>` first.
- To keep the app removed, check that the link is broken (`test -e /opt/<name> || echo broken`, read-only), then `sudo rm /opt/<name>` (changes system: deletes the link only; undo `sudo ln -s /usr/lib/opt/<name> /opt/<name>`). Never use `rm -r` here.

### "signature verification failed" when installing or reinstalling

In progress, rakuos-rum: https://rakuos.org/bugs/b/failed-signature-verification-for-some-rpm-packages-after-trying-to-reinstall-some-apps-that-doesn-t-appear-on-the-overlay-92b56449.

1. Update: `sudo rum system-upgrade`, reboot (undo `sudo bootc rollback`).
2. `sudo rum clean packages`, then retry the install.
3. `does not verify: no signature` from a third-party repo: that repo publishes unsigned packages; use the app's Flatpak or a Distrobox container. Do not turn off signature checking. rpm-ostree, suggested in the thread, is not installed.

### rum says "standalone mode"; updates fail with no free space on /

Open, rakuos-rum (August 2026): https://rakuos.org/bugs/b/rakuos-updates-cannot-be-upgraded-39b15302.

`rum paths` (read-only) should say `mode: split`. If it says standalone: reboot once (the initrd re-creates `/var/lib/rakuos/current-deploy` and mounts the overlay), then check again. If it persists, stop running package commands and report it with `rum paths`, `findmnt /usr` and `journalctl -b -u rakuos-overlay-mount -u rakuos-overlay-sync`. Do not set `diskspacecheck=0`. [Playbook](https://rakuos.org/ai/troubleshooting/rum-standalone-mode).

## Software Center

### "Update All" turns into "Retry" and nothing updates

In progress: https://rakuos.org/bugs/b/some-packages-doesn-t-update-on-rakuos-software-niri-45f8117f. Update from a terminal instead: `sudo rum system-upgrade` (changes system: overlay packages, Flatpaks, then stages the new image; reboot to use it; undo `sudo bootc rollback`). Flatpaks alone: `flatpak update`.

### The Updates page keeps reloading during an image update

In progress, fix announced for the next stable update: https://rakuos.org/bugs/b/why-is-rakuos-software-reloading-during-update-a6b0f08c. Restart the Software Center and run the update again, or use `sudo rum system-upgrade`.

### No progress or reboot message when the only update is a new image

Open: https://rakuos.org/bugs/b/no-progress-bar-or-indication-for-reboot-when-using-full-update-0a8b6f89. Run `sudo bootc status` (read-only): if `staged:` is not `null`, the update is done; reboot.

### "Check for updates: Manual only" goes back to "Daily" after a reboot

In progress (Qt frontend, KDE): https://rakuos.org/bugs/b/update-schedule-setting-resets-on-reboot-8e22fd2d. Set it again after each reboot until fixed.

### "Automatically apply bootc image updates" never applies anything

Found in code (rakuos-core `e08616c`), not on the tracker. The setting enables `rakuos-updater.timer`, which only checks for a new image on Thursdays. Update by hand: Software Center Updates page or `sudo rum system-upgrade`, then reboot.

### An app is listed but fails with "nothing provides '<name>'"

Found in code (rakuos-software `7096eb2`), not on the tracker. The catalog includes Terra's apps, but Terra is disabled by default. If the user wants Terra: `sudo rum config-manager --set-enabled terra` (changes system; undo `--set-disabled terra`; no reboot), then install again. Otherwise look for the app as a Flatpak.

### `rakuos setup-nvidia` installs a driver that won't load

Found in code (rakuos-core `e08616c`), not on the tracker. `setup-nvidia` and `setup-nvidia-legacy` (still in `rakuos --help`) install `dkms-nvidia` / `dkms-nvidia-580xx` into the overlay. The kernel now loads only RakuOS-signed modules (`module.sig_enforce=1`, `lockdown=integrity`), so the DKMS-built module is refused. Both scripts also replace the user's kernel arguments (source `rakuos-user`) with the nouveau blacklist. Instead: remove the DKMS packages (`rum list | grep -i nvidia`, read-only; then `sudo rum remove <pkgs>`), switch to the `-nvidia` image, or `-nvidia-legacy` for Maxwell/Pascal/Volta, and recheck RakuOS System > System > Kernel Parameters…. [Playbook](https://rakuos.org/ai/troubleshooting/kernel-module-wont-load).

## RakuOS System app

### Switching Stable ↔ Staging says "Your overlay stays as it is", then every app is reinstalled

Found in code (rakuos-system `fc07607`), not on the tracker. Staging images are Fedora 45, stable images Fedora 44, but the app only treats Rawhide as a Fedora release change. The first boot after the switch soft-resets the overlay and reinstalls `packages.list` from the network (no pre-download). Keep the network connected for that boot; nothing else is needed. Undo: `sudo bootc rollback` (another reinstall).

### Anti-Cheat check: a kept vendor MOK still shows "Not well-known"

Found in code (rakuos-core `e08616c`). `rakuos enroll-secureboot-key` keeps keys from vendors such as Oracle, Proxmox, the BSDs or Red Hat, but `rakuos eac-check` accepts only Epic's list (Canonical, "Fedora Secure Boot CA", Universal Blue, Debian, openSUSE, SUSE, Rocky, Microsoft UEFI CA, AlmaLinux), so it keeps failing the MOK item and keeps suggesting `enroll-secureboot-key`. Do not delete vendor keys by hand; report it against rakuos-core with the `sudo rakuos eac-check` output. [Playbook](https://rakuos.org/ai/troubleshooting/anti-cheat-not-ready).

## Editions, installer and hardware

### KDE: going to standby asks for a password

Open, rakuos-kde: https://rakuos.org/bugs/b/putting-the-system-into-standby-mode-requires-the-root-password-0b12103b. The reporter says a reboot fixed it. Reboot; if it returns, add the output of `id` and `systemd-inhibit --list` (both read-only) to the report.

### KDE: no app for setting up printers

Open, rakuos-kde: https://rakuos.org/bugs/b/no-gui-for-printer-management-75736374. `system-config-printer` is in KDE images from 2026-10-09 (stable) and 2026-10-07 (staging only): update and reboot. On an older image: `sudo rum install system-config-printer` (changes system; undo `sudo rum remove system-config-printer`; no reboot). CUPS itself is in every image.

### KDE: file search finds nothing ("Unable to open Baloo index")

Open, rakuos-kde: https://rakuos.org/bugs/b/file-search-in-kde-isn-t-working-d55d7792. No verified workaround. Add `balooctl6 status` output and the image date (`sudo bootc status`) to the report.

### Xbox controller, racing wheel or sensor stopped working after an update

By design, found in code (no tracker entry): images built from 2026-10-23 on ship only the `wl` and `v4l2loopback` modules. `xone`, `xpadneo`, `xpad-noone`, the racing wheel drivers (`hid-fanatecff`, `hid-tmff2`, `t150-driver`, `new-lg4ff`, `logitech-trueforce`), `ayaneo-leds`, `sc0710`, `nct6687d`, `ryzen_smu` and `zenergy` came with earlier images and are now opt-in, so updating removes them.

```bash
rum list --base | grep rakuos-kmod   # read-only: what the image ships (wl, v4l2loopback, NVIDIA)
rum list | grep rakuos-kmod          # read-only: what the user installed
```

Fix: RakuOS System › Drivers › Install (the page names the repo each driver needs; most need Terra, turned on in the Welcome app's Third-Party Repositories page), then reboot. Terminal: `sudo rum config-manager --set-enabled terra` and `sudo rum install rakuos-kmod-<name>` with the system's suffix (changes system; undo `sudo rum remove`; reboot). Never `akmod-*`/`dkms-*`. See [Kernel modules and Secure Boot](https://rakuos.org/ai/components/kernel-modules-secure-boot).

### Older Intel laptop: TPM not found, TPM disk unlock stopped (IOMMU)

Reported to the maintainer 2026-10-19 (no tracker issue yet): a ThinkPad X250 booting in legacy mode lost its TPM after the images started booting with `intel_iommu=on iommu.passthrough=0 iommu.strict=1` (2026-10-15), so LUKS TPM2 unlock stopped. Suspected cause, not yet confirmed. Workaround: a one-boot test without those arguments, then `intel_iommu=off` in RakuOS System's Kernel Parameters (EAC v2 games won't start with it). Playbook: [TPM not found or TPM unlock stopped](https://rakuos.org/ai/troubleshooting/tpm-missing-after-iommu).

### Freezes or kernel panics

Open: https://rakuos.org/bugs/b/kernel-panics-aa284459 (reported on COSMIC v2 with NVIDIA graphics, during the P03 kernel period). Update and reboot (`sudo rum system-upgrade`); if freezes began with an update, `sudo bootc rollback`. Only when `lspci` shows an NVIDIA GPU and the image name has no `-nvidia`, consider the matching `-nvidia` image; see the [playbook](https://rakuos.org/ai/troubleshooting/system-freezes) for the checks.
- The -nvidia switch is based on one user report, not a confirmed fix.
- Keep the same edition, x86-64 level and channel when switching. Undo with sudo bootc rollback.
- The NVIDIA driver comes from the -nvidia image (-nvidia-legacy for Maxwell/Pascal/Volta). Do not use RPM Fusion akmod-nvidia, rakuos setup-nvidia or the NVIDIA .run installer.

### System won't boot after an update (niri v3 image of 2026-09-02)

Open: https://rakuos.org/bugs/b/20260902-niri-stable-v3-standard-image-get-stuck-during-boot-5f544825; the 2026-09-04 image works. In the GRUB menu (shown 5 seconds) pick the `(ostree:1)` entry to boot the previous image, then `sudo bootc rollback` (changes system; reboot; undo: roll back again) and update later.

### NVIDIA images lack XWayland driver libraries

Open, nvidia-drivers: https://rakuos.org/bugs/b/packages-for-xwayland-1ec13121. `xorg-x11-drv-nvidia-libs` and `xorg-x11-drv-nvidia-cuda` are missing; some XWayland apps and games need them. Maintainer will add them. No verified workaround.

### MediaTek MT7921 Wi-Fi hangs; reboot freezes

Open, rakuos-base (upstream `mt7921e` driver bug): https://rakuos.org/bugs/b/wifi-hang-requiring-hard-reset-occurred-2x-19e9f320. Confirm with `journalctl -b -1 | grep -E "driver own failed|chip reset failed"` (read-only). Update to the newest image; use a USB Wi-Fi adapter or Ethernet meanwhile.

### Encrypted install fails in the text-mode installer

Found in code (rakuos-installer `f93ef72`), not on the tracker: the text installer's encryption choices are rejected (`encryption.type "luks" is not valid`). Use a graphical installer (KDE, GNOME, COSMIC or niri ISO) for an encrypted install.

## Recently fixed

| Issue | Marked fixed or closed (tracker date) | Tracker |
|---|---|---|
| "Nvidia Legacy" offered on Stable with no image to switch to | 2026-10-17: stable now builds `-nvidia-legacy` images (image repos `main`), found in code, no tracker entry | image CI |
| Staging on kernel 7.2.10: Xbox controllers (`xone`, `xpadneo`, `xpad-noone`), `v4l2loopback` and MT7927 Wi-Fi modules missing | 2026-10-15, found in CI (no tracker entry): signed-kmods build 7 covers 7.2.10; update to the newest staging image and reboot | signed-kmods `727282b` |
| Software Center does nothing when opened (niri) | 2026-09-27; on older images quit it from the tray and update | [82a07770](https://rakuos.org/bugs/b/rakuos-software-center-rakuos-software-gtk-fails-to-open-on-niri-image-82a07770) |
| Software Center lost its System tab | 2026-09-30: moved to the RakuOS System Management app | [3df8d05a](https://rakuos.org/bugs/b/260930-rakuos-niri-image-lost-the-system-tab-in-rakuos-software-3df8d05a) |
| Option to turn off the Software Center tray | 2026-09-27 (Settings, Tray Icon) | [e4ffd2b6](https://rakuos.org/bugs/b/feature-request-add-a-toggle-in-rakuos-software-to-disable-tray-app-and-background-operation-e4ffd2b6) |
| Portal "Save As" dialog dropped the file name | 2026-09-27 (rakuos-settings) | [9ff3c7b7](https://rakuos.org/bugs/b/portal-save-as-dialog-drops-download-filename-saves-only-the-extension-9ff3c7b7) |


---

# Reporting a bug

Help the user file a bug only when RakuOS code is wrong, not when the problem is the user's setup or a question about how something works. RakuOS bugs are filed at https://rakuos.org/bugs under the project that owns the broken part; filing needs an account on rakuos.org.

As of 2026-10-14.

## Bug, support question, or upstream?

| It is… | When | Send the user to |
|---|---|---|
| A **known issue** | It matches an entry in [known issues](https://rakuos.org/ai/known-issues) | that tracker issue: add details there instead of filing a new one |
| A **support question** | RakuOS behaves as documented, but the user expected something else, or their own change caused it (an edited config file, a repo they added, a hand-installed file in `/usr`) | the documented fix; otherwise the forum (rakuos.org/forum), Matrix (matrix.rakuos.org) or Discord |
| An **upstream bug** | The fault is in software RakuOS only packages unchanged (a Flatpak app, a Fedora package, a vendor's `.rpm`, a Linux driver) and happens the same on Fedora | that project's tracker; mention it on the RakuOS tracker only if RakuOS packaging is involved |
| A **RakuOS bug** | A RakuOS tool or image does something wrong: a crash, a wrong result, an error message from rum, rakuos-core, the Software Center, the RakuOS System app, the installer, or an image missing something it should have | file it, as below |

Stop troubleshooting once it is clearly a RakuOS bug. More fixes change the system away from the state the developers need to see.

## Pick the project

Use the table "Which project owns the problem" in the [repo map](https://rakuos.org/ai/repo-map#which-project-owns-the-problem). Common cases:

- `rum` or `dnf` errors: rakuos-rum.
- Files missing under `/usr`, overlay resets, "RakuOS overlay" boot messages: rakuos-core.
- The Software Center: rakuos-software. The RakuOS System Management app: rakuos-system.
- Installing from the ISO: rakuos-installer; a live ISO that won't boot: the edition's ISO project.
- Something one desktop edition does or lacks: that edition's image project (rakuos-kde, rakuos-gnome, rakuos-cosmic, rakuos-niri, rakuos-hyprland, rakuos-gamescope).
- NVIDIA driver problems: nvidia-drivers (https://rakuos.org/bugs/p/rakuos-packages-drivers-nvidia-drivers).
- Not sure: the edition's image project.

Project pages are `https://rakuos.org/bugs/p/rakuos-` plus the repo path with `/` replaced by `-`, for example `https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-rum`. Check the project's open issues for a duplicate first.

## Collect the information

1. Run the read-only [diagnostics block](https://rakuos.org/ai/troubleshooting/diagnostics) and keep the output. The template's own block starts with `cat /etc/os-release`; on RakuOS `cat` is bat, which adds line numbers and may open a pager (press `q`), so use `gnu_cat /etc/os-release` for text to paste. If the problem happened before the last reboot, use `-b -1` in the `journalctl` lines.
2. For a package problem, add `rum origin <pkg>` and `rpm -V <pkg>`.
3. Write down every command already run, including commands an AI assistant suggested, and what each did.
4. Note the exact error text, copied, not paraphrased.

## Redacting logs

Before the user pastes anything, remove or replace:

- user names (also in paths such as `/var/home/<user>`),
- host names,
- IP and MAC addresses,
- e-mail addresses,
- serial numbers and machine IDs.

Keep image names, versions, digests, kernel versions, package names and error messages: they are what the developers need.

## Fill in the template

The report format is in `bug-report-template.md`. Fill in each section with the user:

- **Title**: the symptom and when it happens, e.g. "Overlay packages lose their files after an image update".
- **Summary**: one or two sentences: what is broken and since when.
- **Environment**: edition and channel (from `VARIANT_ID`), booted and rollback image with version (from `sudo bootc status`), kernel (`uname -r`), hardware, recent changes.
- **Steps to reproduce**, **What happened** (exact errors in code blocks), **What I expected**.
- **Logs**: the redacted diagnostics output.
- **What I already tried**: every command run and its effect.
- **Workaround**, if any; **Suggested fix**, only with a link to the RakuOS source file and line.
- **Checklist**: searched for duplicates; removed personal information; and, if an AI helped, that the user checked every detail.

Have the user confirm every detail before filing. The user files the report themselves while logged in to rakuos.org.