Troubleshooting

Most problems on a rolling-release system come from one of three things: a system that has not been updated in a while, a signature check that cannot succeed because a keyring is out of date, or an update that changed something you were relying on. This page covers all three, and then explains where to report what is left.

If you are stuck, the Discord channel is the fastest place to ask.

Updating is not optional

Ditana is Arch Linux underneath, and Arch is a rolling release. There is no “version” to stay on: there is one moving target, and every package in the repositories is built against the libraries that are current today. A system that has not been updated for a few months is not a stable older system — it is a system whose next update is a large, untested jump.

Two consequences are worth stating plainly:

• Security fixes only arrive if you update. There is no separate backport channel. The fix for a vulnerability in a library reaches you as a new version of that library, and not otherwise.

• Never update a single package. pacman -Sy something synchronises the package databases and then installs one package against libraries that may already have moved on. This is a partial upgrade, it is the single most common way to break an Arch system, and it is unsupported. Update everything or nothing: -Syu, never -Sy followed by an install.

  (The one deliberate exception is the keyring repair below, and it is safe for a specific reason that is explained there.)

The graphical way

Ditana installs a software centre on every desktop:

Tool	Installed with	Covers
Pachub	XFCE, Niri, Wayfire, COSMIC	Packages from the Arch and Ditana repositories
Bazaar	Niri, Wayfire	Flatpak applications from Flathub
COSMIC Store	COSMIC	Flatpak applications from Flathub
Kalu	XFCE	Notifies you when updates are waiting
arch-audit-gtk	all desktops	Tray indicator that turns red when an installed package has a known vulnerability

Pachub and the Flatpak stores cover different halves of the system, so running one is not the same as running both. If your desktop has no Flatpak store, the terminal command below covers it.

The terminal way

This is the recommended route, because one command covers the repositories and the AUR packages you have installed:

paru -Syu          # Arch repos + Ditana repo + your AUR packages
flatpak update     # sandboxed applications from Flathub

paru is Ditana’s chosen AUR helper and is installed on every system, including headless ones. Plain pacman -Syu also works, but it leaves AUR packages behind — and an AUR package left behind while its dependencies move on is exactly the ABI mismatch that produces “symbol lookup error” a week later.

After the update

• Configuration files. When a package ships a new default for a file you have edited, pacman writes it beside yours as *.pacnew and says so. Merge them with sudo pacdiff (from pacman-contrib, installed by default). Ignoring .pacnew files for a year is a slow way to accumulate breakage.
• Reboot after a kernel update. Until you do, the running kernel no longer matches the modules on disk, and loading a module that was not already in memory will fail.
• Snapshots. If you enabled automatic snapshots during installation, the state before the update is still on disk and you can boot into it. See Automatic system snapshots.

“invalid or corrupted package (PGP signature)”

Every package Ditana ships is signed, and pacman refuses to install one whose signature it cannot check. That is the mechanism working. But it also means a keyring that is out of date locks you out of the very updates that would fix it.

You will see one of these, depending on whether the signing key is missing from your keyring or present but not trusted:

error: ditana-mirrorlist: key "BC333E9AE877D45A" is unknown
:: Import PGP key BC333E9AE877D45A? [Y/n]
error: 'ditana-mirrorlist-1.12-1-any.pkg.tar.zst': invalid or corrupted package (PGP signature)

error: ditana-mirrorlist: signature from "Stefan Zipproth <[email protected]>" is unknown trust
error: failed to commit transaction (invalid or corrupted package (PGP signature))

The repair

For a Ditana package:

sudo pacman -Sy ditana-keyring

For an Arch package (the same problem, the same shape — this one is common on systems that have been offline for months):

sudo pacman -Sy archlinux-keyring

This is the exception to the “never -Sy a single package” rule above, and it is worth understanding why it is safe rather than treating it as a magic incantation. Only one package is in the transaction, so there is no partial upgrade of a dependency graph. That package is small and contains no executables. And its signature is verifiable with a key your installation already has, so nothing is being trusted that was not trusted before — installing it runs pacman-key --populate, which adds the current set of Ditana keys to your keyring. Afterwards, run a full update as usual.

If you would rather do it by hand, this is exactly what the package’s install script runs:

sudo pacman-key --populate ditana

Verify the keys yourself

Ditana packages are signed by this key:

pub   rsa4096  3F80 54C3 FF75 5E55 44E6  8516 BC33 3E9A E877 D45A
uid   Stefan Zipproth <[email protected]>
uid   Stefan Zipproth <[email protected]>

It carries a dedicated signing subkey, which may be used for package signatures in future:

sub   rsa4096  068E EA2A 490B 0C63 AEAA  3BCD 3EC2 23A8 1107 7C09

Check what your own system trusts with:

pacman-key --list-sigs ditana
gpg --show-keys --with-subkey-fingerprint /usr/share/pacman/keyrings/ditana.gpg

We deliberately do not offer a download-and-run repair script here. The situation you are in is “my signature verification is failing”; answering that with “download this and execute it as root” is formally the same operation the signatures exist to prevent, and the script could not be meaningfully signed either — the signature check is the broken part. One command you can read is better than a black box.

Other causes of the same message

• The clock is wrong. A signature is not valid before it was made. If the system clock is far in the past — a drained CMOS battery, a fresh VM, a dual boot with Windows writing local time to the RTC — every signature looks like it is from the future. Check with timedatectl and enable NTP with sudo timedatectl set-ntp true.
• A mirror served a truncated file. The message mentions a checksum rather than a PGP signature in that case. sudo pacman -Scc clears the download cache and retries.

An update broke something

1. Check whether it is us. The build status page shows every package build, including the ones that were held back. If the last run was held back, the repository has not changed since the one before it, and the cause is elsewhere.
2. Boot the snapshot. With automatic snapshots enabled, the pre-update state is a boot menu entry away. This is the fastest way to get a working system back, and it costs nothing to try.
3. Check what actually changed. /var/log/pacman.log lists every upgraded package with a timestamp, so you can narrow the search to what moved.
4. Read the news. Arch announces every change that needs manual intervention at archlinux.org/news. If an update needed a step you did not take, it is usually there.

Reporting a bug

Ditana is developed in two repositories, and the right one follows from a single question: did the problem appear while installing, or while using an installed system?

• ditana-installer — the ISO and the installation process. The live environment does not boot; the installer stops with an error; disk partitioning or encryption fails; the installed system does not boot at all; something you selected in the installer’s dialogs did not end up on the installed system.

• ditana-config — what an installed Ditana system is. Package selection, desktop configuration, defaults and dotfiles, systemd units, kernel parameters and CPU mitigations, Ditana’s own helper scripts. If the system boots and something in it is wrong or missing, this is the place.

If you cannot tell, open it in ditana-config and say so — it is easier to move an issue than to have it go unreported.

A useful report contains:

• The Ditana version from lsb_release -a, and the kernel from uname -r.
• What you expected, what happened, and the exact command or click that produced it.
• The relevant error, copied as text rather than photographed.
• For an installer problem: /var/log/install_ditana.log, which the installer also copies into the installed system.
• For a service that fails: systemctl status <unit> and journalctl -u <unit> -b.
• For a hardware problem: print-system-infos, which is installed on every Ditana system and summarises CPU, GPU, memory and firmware in one screen.

Please do not report AUR packages here. Ditana rebuilds 43 recipes from the AUR unchanged; if the software itself is broken, the AUR page or the upstream project is where a fix can actually be made. If the packaging in Ditana’s repository is at fault — a missing dependency, a package that will not install — that is a ditana-config issue and we do want to hear about it.