# Arch Troubleshooting

Use for boot, service, package transaction, upgrade, and app failures.
Start read-only.
Identify last change.

## Baseline

```sh
cat /etc/os-release
uname -a
systemctl --failed
journalctl -b --no-pager -p err..alert
tail -n 80 /var/log/pacman.log
```

For app issue:

```sh
command -v app
pacman -Qo "$(command -v app)"
pacman -Qi package
```

If command substitution conflicts with user shell, split into two commands.

## Package Transaction Errors

Lock:

- Verify no pacman/makepkg/AUR helper process is running before removing lock.
- Current lock path/safe handling:
  check wiki/man.

Conflicting files:

```sh
pacman -Qo /path/to/conflict
```

If unowned, investigate origin before rename/delete.
Avoid `--overwrite` unless current Arch guidance says so.

Target not found / retrieval failed:

- Verify package exists:
  `archlinux.org/packages`, `pacman -Ss`, AUR if unofficial.
- Check enabled repos + mirror freshness.
- Do not fix with `pacman -Sy <pkg>`.

Invalid/corrupt package/signature:

- Check current wiki `Pacman/Package signing` + Arch News.
- Suspect stale keyring, partial downloads, bad mirror only after evidence.

Interrupted upgrade / broken pacman / unbootable:

- Fetch current wiki `Pacman#Troubleshooting` before procedural advice.
- Prefer live ISO + mount + `arch-chroot`/`--sysroot` recovery path.
- Reconstruct exact failed transaction from `/var/log/pacman.log` when relevant.

## Software Failures

Classify:

- packaging issue?
  upstream bug?
  config?
  missing optional dep?
  partial upgrade?
  service sandbox?
  permissions?

Probes:

```sh
pacman -Qi package
pacman -Ql package | less
pacman -Qii package
journalctl -b --user --no-pager
journalctl -b --no-pager -u unit.service
```

Missing `.so` after upgrades usually means partial/incomplete upgrade or
unrebuilt local/AUR package.
Do not symlink libs.

## Output Shape

```text
Observed: ...
Likely cause: ...
Evidence: ...
Safe checks: ...
User-run root step, if needed: ...
Rollback/logs: ...
```