Diagnose the FreeBSD boot path

Synopsis #

A machine that “does not boot” can have failed before FreeBSD starts, inside the loader, while the kernel attaches devices, while the root filesystem is selected, or during multi-user service startup. The last reliable output determines the next diagnostic step.

Preserve that output and change one layer at a time. Do not reinstall a boot loader, repair a filesystem, import a ZFS pool, or roll back a dataset merely because the screen stopped. Those actions solve different failures and some are destructive.

Record the last completed stage #

Use a local display, provider console, baseboard management controller, or tested serial recovery console . Photograph or capture the complete error and the messages immediately before it. Record whether the failure began after firmware changes, disk work, an update, an upgrade, a kernel or loader setting, or an rc.conf change.

Classify the boundary before changing anything:

Check firmware and boot selection #

If firmware output is absent, FreeBSD files are not yet involved. Confirm power, hardware status, display or console selection, and any remote-management event log. Revert only a known recent firmware change through the hardware’s documented recovery mechanism.

If firmware works, open its one-time boot menu and confirm the intended disk and boot mode. UEFI and legacy BIOS paths use different boot components. A firmware update or reset can remove or reorder a UEFI boot entry without changing the FreeBSD filesystem.

From a working installation or official recovery environment, gather read-only layout evidence:

# gpart show
# gpart show -p

Do not run gpart bootcode, format the EFI System Partition, or create new partitions until the installed boot mode, partition scheme, and missing component have been proved. The installation preflight describes safe media and disk identification.

Use the loader as a diagnostic boundary #

An interactive FreeBSD loader proves that firmware reached boot code capable of reading at least part of the boot filesystem. Stop the countdown and inspect the loader’s current view:

show currdev
show loaddev
show kernel
lsdev

Command availability varies between loaders and platforms; use help and the installed loader(8) manual. Compare the displayed devices and paths with the recorded installation layout.

For a one-boot diagnostic, verbose mode can expose the kernel’s last successful attachment:

boot -v

Single-user mode is appropriate only after the kernel can reach the root filesystem:

boot -s

If a loader variable added to /boot/loader.conf caused the failure, override or unset that exact variable for one boot at the loader prompt. Correct the persistent file only after the system starts. Do not copy unrelated tunables. The persistent-settings guide separates loader, kernel, and service configuration.

A known previous kernel may be tested through the loader when the relevant files exist, but kernel.old is not guaranteed to be present or compatible with the current userland and modules. Preserve the failed kernel and record exactly which kernel boots instead of replacing files immediately.

Separate kernel attachment from root selection #

When kernel messages start, note the last driver, device, and error. A final line naming a device can be the last successful attachment rather than the cause. Repeat one boot with -v and compare the sequence with /var/run/dmesg.boot from a known-good boot, if available.

If the kernel asks for a root device or reports that the root cannot be mounted, verify:

• whether the expected storage controller and disks attached;
• whether device identifiers changed after controller or cabling work;
• whether the loader selected the intended boot device;
• whether the root pool or filesystem name in the error matches the installation record;
• whether encryption material or another prerequisite is available.

The loader’s -a boot flag can request an interactive root-device selection, but a successful manual selection is diagnostic evidence, not a permanent fix. Correct the underlying device or configuration reference after the running layout is known.

Treat UFS and ZFS failures differently #

For UFS, fsck(8) must operate under the conditions described by its manual page, normally while the filesystem is unmounted or mounted read-only. Do not apply an automatic repair flag to a disk that has not been identified or to a filesystem that is mounted read-write.

For ZFS, first inspect rather than import or modify:

# zpool import

This lists pools visible to the recovery environment without importing a named pool. Import options, alternate roots, encryption, host identifiers, and bootfs properties affect a safe recovery plan. A pool that is already imported by another running host must not be force-imported as a routine diagnostic step.

If a pre-change ZFS boot environment exists and the loader can read the pool, follow Recover with a ZFS boot environment . A boot environment is not a pool repair, does not restore separate data datasets, and should not be replaced with a blind zfs rollback.

Isolate init, rc, and service failures #

If the root filesystem mounts and init starts, the loader and kernel have completed their primary work. Enter single-user mode from the loader or through the documented boot menu. Single-user mode has no normal network service startup and provides privileged local access; apply the physical-console policy described by the FreeBSD boot documentation.

Inspect the exact recent configuration change and the previous boot log. On a system that reaches multi-user mode, useful read-only checks include:

# dmesg -a
$ service -e
# service service-name status

Replace service-name with an enabled service reported near the failure. Disable or correct only the proved failing service using its documented rc variable. A blanket removal of /etc/rc.conf, firewall rules, storage mounts, or package startup scripts destroys evidence and can introduce a second outage.

When a release update or upgrade was interrupted, continue with Recover from an interrupted FreeBSD update after the system can boot safely. Do not resume package or base-system changes while storage health remains uncertain.

Use recovery media without committing changes #

Boot official installation media for the installed architecture when the loader, kernel, or root environment cannot provide a shell. Select its live or shell facility and first inventory disks, partitions, and pools. Keep the installed root unmounted until its identity and recovery objective are clear.

Recovery media can have a different kernel and driver set from the installed release. A disk visible there but absent from the installed kernel points toward an installed-kernel, module, or configuration difference; it does not by itself prove disk health.

Before any write, record:

• the exact target device, partition, pool, or dataset;
• whether it is mounted or imported elsewhere;
• the command’s rollback or backup path;
• the evidence connecting that operation to the failed stage.

If no safe write follows from the evidence, preserve the machine state and collect storage or hardware diagnostics instead of trying a universal repair command.

Primary references #

• FreeBSD Handbook: The FreeBSD Booting Process
• FreeBSD Handbook: Installing FreeBSD
• boot(8)
• loader(8)
• init(8)
• rc(8)
• gpart(8)
• fsck(8)
• zpool-import(8)