Troubleshooting

Where to look

what	where
the automatic daily update	`journalctl -u based-update`
security fixes it installed	`/var/log/unattended-upgrades/`
an update you ran	its terminal, and `journalctl -t based-update`
what the edition package applied	`/var/log/based-edition.log`
what's waiting to update	`based-update pending`
your home's defaults	`journalctl --user -u based-converge`
onboarding's steps	`based-onboard-tasks list`
the theme and desktop settings	`desktop-sync status`, and `journalctl --user -u desktop-sync`
anything else from this boot	`journalctl -b -p warning`

Running things again

The update is based-update, and running it again after a failure retries what didn't finish. An onboarding step that didn't finish runs again at your next login, or now:

based-onboard-tasks run

Finish setting up Based in your apps opens onboarding again.

Your home's defaults are brought up to date at every login, but only when a package they come from has changed. To make the converge look again anyway:

rm ~/.local/state/based/converge/packages
systemctl --user start based-converge

Your config files says what it will and won't touch.

Locked out

If the desktop won't start, switch to a text console with Ctrl+Alt+F3 and log in there. On Poweruser the lock screen refuses you for two minutes after ten wrong passwords. Wait it out, or from a console:

sudo faillock --user "$USER" --reset

Getting back to before an update

A machine installed with the graphical installer on btrfs, the default, takes a snapper snapshot before every apt run. The boot menu lists them in a submenu, so after a bad update you can boot the system as it was.

sudo snapper list

The text installer, ext4 or xfs, and an install onto an existing system have no snapshots.

A btrfs install also takes @factory, a read-only snapshot of the system as the installer left it. Setup, then Reset Computer erases homes and starts first-run setup again. Reset System, Keep Files puts only the system back. Both keep your password. They show only on a btrfs install that has @factory; sudo based-system-reset --erase and --keep-files do the same from a terminal.

Reporting a bug

Collect four things first:

the whole of cat /etc/based-release, pasted
the steps, in order, from a fresh boot
what happened, and what you expected instead
journalctl -b -p warning for the boot it happened on

omarchy debug gathers the hardware, package list and warnings into one file. Its Upload choice posts to Omarchy's own log service, which isn't where Based bugs go, so pick Save instead and attach the file.

/etc/based-release names the places to send it: https://basedlinux.com/support for help and https://basedlinux.com/issues for bugs. Neither is online yet. Until they are, there's no public tracker to send a report to.