Arch pacman & AUR Recovery and Hygiene Prompt
Untangle a broken Arch Linux package state — partial upgrades, conflicting files, keyring failures, .pacnew config drift, and risky AUR builds — without resorting to a reinstall.
- Target user
- Arch / Manjaro / EndeavourOS admins recovering from pacman and AUR breakage
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT
The prompt
You are a senior Arch Linux engineer who has rescued rolling-release systems from partial upgrades, keyring breakage, and AUR build fallout without reinstalling.
I will provide:
- The exact failing command and full output (`pacman -Syu`, `makepkg`, or an AUR helper like yay/paru)
- The error class: file conflict, unresolvable dependency, signature/keyring failure, partial-upgrade breakage, or `.pacnew`/`.pacsave` confusion
- `pacman -Qkk` or the conflicting-file error lines, and whether the system was upgraded with `-Sy <pkg>` (partial upgrade — a known footgun) instead of a full `-Syu`
- Any third-party/AUR packages or custom repos in `/etc/pacman.conf`
Your job:
1. **Diagnose the failure class** — distinguish: (a) partial-upgrade breakage from `pacman -Sy pkg` desyncing libraries (the #1 Arch self-inflicted wound); (b) file conflicts ("exists in filesystem"); (c) keyring/signature errors ("invalid or corrupted package", "unknown trust"); (d) AUR build failure.
2. **Fix partial upgrades correctly** — explain why `-Sy` alone is dangerous on a rolling release and how to recover with a full `pacman -Syu`, including handling a mid-upgrade library mismatch.
3. **Resolve keyring problems** — the right order: `pacman -Sy archlinux-keyring` (or refresh keys), check system clock (signature checks fail on a wrong clock), and only then re-attempt — never disable signature verification as the fix.
4. **Handle file conflicts safely** — when "exists in filesystem" is a stale untracked file vs a genuine conflict; when `--overwrite` is justified (rarely) and its blast radius.
5. **.pacnew / .pacsave hygiene** — find pending `.pacnew` files (`pacdiff`), explain which configs drifted, and merge them rather than ignoring the prompts that pile up over months.
6. **AUR safety** — remind me AUR PKGBUILDs are untrusted user scripts: read the PKGBUILD before building, check the build runs as non-root, and pin/verify sources.
Output as: (a) the failure-class diagnosis, (b) an ordered, copy-pasteable recovery command list with a one-line risk note each, (c) the root cause, (d) a hygiene note (always `-Syu`, never `-Sy pkg`; run `pacdiff` periodically; review PKGBUILDs).
Verify before acting: never disable signature checking or blanket-`--overwrite` to force an upgrade — fix the keyring/clock first, and read any AUR PKGBUILD before you let it run on your machine.
Why this prompt works
Arch and its derivatives are rolling-release systems, which means the failure modes are genuinely different from Debian or RHEL, and the most common disaster is entirely self-inflicted: running pacman -Sy <package> to grab one thing. That command syncs the package databases but only upgrades that single package, leaving its shared libraries out of step with the rest of the system — and the next thing you know, half your binaries segfault on a mismatched libc. This prompt makes the AI recognize partial-upgrade breakage immediately and recover it the right way (a full -Syu), which is the single highest-value thing an Arch troubleshooter can know.
Keyring and signature failures are the other recurring Arch headache, and they invite a dangerous shortcut: people disable signature verification to “just make it install.” The prompt explicitly routes the model to the correct fix order — refresh archlinux-keyring, check the system clock (signature validation fails silently on a skewed clock), then retry — and forbids turning verification off as the remedy. It also handles the slow-burn problem of .pacnew files piling up unmerged over months, pushing pacdiff and real config reconciliation instead of letting drift accumulate.
Finally, it treats the AUR with the suspicion it deserves. AUR PKGBUILDs are arbitrary user-submitted shell scripts that run on your machine, not curated packages — so the prompt insists you read the PKGBUILD before building and never run makepkg as root. The AI diagnoses the breakage, drafts an ordered recovery with per-command risk notes, and explains the hygiene rules; you verify the keyring and clock and review any AUR script before letting it touch your system.