Recover an interrupted freebsd-update run

Synopsis #

freebsd-update separates fetching, merging, and installation into saved phases. During a release upgrade, repeated freebsd-update install invocations intentionally perform different work around a reboot and third-party package upgrade. An interruption does not therefore imply that the process must start again.

Do not remove /var/db/freebsd-update, change the target release, or start another update job while diagnosing the saved transaction. Those actions can destroy the state needed to continue safely.

This procedure applies to a distribution-set base system. A pkgbase host is maintained with pkg; identify the method with the update and upgrade decision guide .

Record the current state #

Capture the exact error and the three installed version values:

$ freebsd-version -kru
$ uname -a
$ df -h / /var
$ mount

Check for another active process before starting a replacement invocation:

$ pgrep -laf freebsd-update

If an active process is still fetching, merging, or installing, investigate that process rather than running a concurrent copy. An abandoned terminal does not necessarily mean the process stopped.

Interpret the phase #

The saved upgrade state makes the next install invocation advance to the appropriate phase. Do not repeat upgrade -r merely because the shell session ended.

Continue a saved transaction #

When no other update process is running and storage is writable with adequate free space, run:

# freebsd-update install

Read its output. A message that no updates are available is different from a failed saved phase. If a kernel was installed but has not been booted, compare the running and installed kernel:

$ freebsd-version -kr

When they differ at the kernel phase, reboot before installing userland:

# shutdown -r now

After booting, record the versions again and continue with freebsd-update install. During a major release upgrade, complete the package ABI step at the point requested by the official release instructions, then make the final install call to remove obsolete base-system files.

Diagnose a repeated failure #

If the same phase fails again, preserve its full output and check:

• free space in /var and the update work directory;
• whether /, /boot, or /var became read-only;
• DNS and HTTPS reachability when the failure occurs during fetch;
• local modifications named in a failed configuration merge;
• a custom kernel or nondefault Components setting;
• the target release’s errata for a known upgrade issue.

Do not respond to a checksum, signature, or metadata error by disabling verification. Do not delete a configuration file simply to force a merge. Correct the underlying storage, network, or merge failure and rerun the same saved phase.

Roll back only the most recent installed update #

For a patch update that installed successfully but caused a regression, freebsd-update rollback uninstalls the most recently installed update:

# freebsd-update rollback

Review the proposed changes and reboot when the kernel or modules changed. This rollback is not a general undo mechanism for every phase of a release upgrade, and the configured backup kernel is managed separately. A ZFS-root system with a known pre-change boot environment can instead use the narrower boot-environment recovery procedure .

Primary references #

• FreeBSD Handbook: binary updates and release upgrades
• FreeBSD 15.1-RELEASE upgrading instructions
• freebsd-update(8)
• freebsd-update.conf(5)
• freebsd-version(1)