Troubleshooting

Most failure points here fail loud on purpose: a log file, a marker file, or a systemd unit you can inspect directly, rather than a silent skip.

The installer fails

Check install.log in /root/sobarch-install/ (the same directory the generated archinstall config is saved to); see Installation. The install command is safe to re-run: it just re-fetches the repo and relaunches the TUI from the start.

A first-boot step doesn't seem to have run

The package-install, security-baseline, and rescue-ISO units only start once a network connection comes up, not at ordinary boot; see First Boot for why. If you've connected and it still hasn't run, check the unit directly:

systemctl status sobarch-firstboot-packages.service
journalctl -u sobarch-firstboot-security.service
journalctl -u sobarch-firstboot-rescue.service

The rfkill, skel, and git-setup units are enabled at ordinary boot instead (sobarch-firstboot-rfkill.service, sobarch-firstboot-skel.service, sobarch-firstboot-git.service); check them the same way.

Each network-triggered unit is safe to start by hand if you don't want to wait for the dispatcher: systemctl start --no-block sobarch-firstboot-packages.service.

A config update left `.sobarch-new` files

That means a file you edited also changed in the new defaults and the two couldn't be merged automatically; your version is untouched. Run sobarch review-conflicts (or Sobarch → Review Conflicts) to keep yours, take the new one, diff, or edit the merge. See Updating Your Config.

Boot & Login Theming covers what should be showing at each stage. Running Update System re-applies all three unconditionally, which is the quickest way to rule out a one-off glitch before digging further.

Hyprland doesn't seem to pick up a config change

Run hyprctl reload directly. Hyprland's own config watcher can miss an atomic file replace (the kind Updating Your Config's merge does), so a change landing on disk doesn't always mean it's been picked up yet.

A vendored package fails to build

The package sync mechanism runs in the background after an upgrade, so its output isn't in your pacman session. A failure raises a critical notification; for the details, read the log or the journal:

less /var/log/sobarch/aur-sync.log
journalctl -u sobarch-aur-sync

To retry a single package directly instead of waiting for the next upgrade:

sobarch aur-sync <package-name>

An "unable to lock database" message just means another pacman operation was running; the sync retries on its own for a short while. A "refusing to build unvendored package" message means the name isn't in the repository's vendored set; the sync only builds those.

Update notifications never appear

The daily check is a systemd user timer. Confirm it's scheduled with systemctl --user list-timers sobarch-update-check.timer, and run it once by hand with systemctl --user start sobarch-update-check.service (it logs to journalctl --user -u sobarch-update-check). It stays quiet when you're offline, and it won't repeat a notification for a backlog it has already told you about, other than weekly.

Applications hang asking for a keyring unlock

Chromium-based browsers and other apps that store secrets need the login keyring unlocked. Log out and back in through the login screen so it's unlocked with your password; see Security for how this is wired up. If it still hangs, check that the first-boot security unit finished: systemctl status sobarch-firstboot-security.service.

Something broke and you want to go back

Snapshots cover both recovering a file from the boot menu and restoring an older snapshot as the new root, including from a live ISO if the system won't boot at all.

Reporting a bug

Run sobarch doctor --write (or Sobarch, Diagnostic Report, in the menu) and attach the file it writes to your issue.

The report lists sobarch package, kernel, and Hyprland versions, a hardware summary, failed units, journal and aur-sync log tails, first-boot state, and snapshot and boot-entry state. Hostname, username, IP and MAC addresses, serial numbers, and UUIDs are replaced with placeholders before the file is written, but read it before posting. Snapshot details need root, so run sobarch doctor where sudo works without a password prompt to include them; otherwise those sections say they were skipped.

Edit this page on GitHub