Fixing a Corrupted GPT Boot Partition on FreeBSD

A FreeBSD host that no longer boots may have damaged GPT metadata, missing EFI files, stale firmware variables, broken BIOS bootcode, or an unreadable root filesystem. Those are separate failures. gpart recover repairs GPT metadata from its redundant copy; it does not recreate an EFI loader, repair UFS or ZFS, or invent partitions when both GPT copies are lost. Diagnose from trusted rescue media before issuing any write.

Inventory firmware mode, disks, and evidence

Boot installation media for the same architecture and choose a live shell. Disconnect unrelated removable disks where practical so device-number changes cannot direct a command at the wrong target. Record the device names, sizes, serials, and partition view:

camcontrol devlist
geom disk list
gpart show -p

Do not assume the failed system’s ada0 remains ada0 under rescue media. Match capacity and hardware identity. Photograph or save gpart show -p before making changes. If the disk is physically failing—timeouts, I/O errors, disappearing device, or unreadable sectors—clone it to healthy media first. Repeated recovery writes against failing hardware can consume the last readable copy.

gpart show can label a GPT scheme CORRUPT when one header is inconsistent or when the backup table is no longer at the physical end after a disk grew. A fully visible partition list with CORRUPT is different from a disk showing no recognized scheme. Check kernel messages for read errors before interpreting either condition as purely logical corruption.

Recover GPT only when one valid copy remains

GPT stores a primary header and table near the beginning of the disk and a backup near the end. After confirming the correct provider, recovery is intentionally short:

gpart recover ada0
gpart show -p ada0

Substitute the verified disk. gpart recover attempts to recover a corrupt partition table and also relocates GPT backup metadata to the end of resized media. It changes disk metadata, so capture the pre-repair layout and have a sector-level backup when the data matters.

Afterward, verify every partition’s start, size, type, and label against installation records, /etc/fstab, ZFS labels, or another identical system. “The command exited zero” does not prove the reconstructed table describes the intended layout. Do not use gpart create, add, or destroy as exploratory commands: they can replace the metadata you are trying to recover.

If neither GPT copy is valid, stop. Reconstructing exact boundaries may require backups of the partition table, filesystem signatures, ZFS labels, and forensic tools. Guessing starts and sizes is not the same as GPT recovery.

Identify whether the machine boots with UEFI or legacy BIOS

The partition type determines the next branch. An efi partition is a FAT-formatted EFI System Partition. A freebsd-boot partition contains FreeBSD bootcode for legacy BIOS/GPT boot. Some disks contain both, but the active firmware path uses only one.

For UEFI, inspect the firmware entries and the EFI System Partition:

efibootmgr -v
mkdir -p /mnt/esp
mount_msdosfs /dev/ada0p1 /mnt/esp
find /mnt/esp/EFI -maxdepth 3 -type f -print

Use the actual efi partition, not blindly p1. A FreeBSD-specific entry commonly points to \EFI\freebsd\loader.efi; the fallback filename depends on architecture, such as BOOTX64.EFI for amd64. The path shown by efibootmgr -v is stronger evidence than a generic recipe.

If the FAT filesystem will not mount, preserve or image it before attempting repair. GPT recovery cannot fix its contents. If it mounts and the expected file is absent or stale, back up the ESP and install the loader.efi from the target FreeBSD system’s matching update, following that release’s installation or release notes. Copying a loader from arbitrary rescue media can introduce a base/boot mismatch.

Firmware may also have lost its NVRAM boot entry while the ESP is intact. efibootmgr(8) can create and activate entries, but its device and path arguments must match the machine. Prefer reconstructing the known previous entry or using the architecture’s fallback path over inventing an unverified command.

Reinstall legacy BIOS bootcode with the filesystem-specific loader

For a BIOS system using GPT and UFS root, the documented pattern is:

gpart bootcode -b /boot/pmbr -p /boot/gptboot -i 1 ada0

For BIOS boot from ZFS, the partition bootcode is gptzfsboot, not gptboot:

gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada0

The -i value must identify the verified freebsd-boot partition. These commands are not EFI repair commands and must not target a FAT ESP. FreeBSD 14’s release notes also document minimum legacy boot-partition sizes and warn that root-pool feature upgrades can require compatible bootcode. Read the notes for the installed release before writing.

If the disk uses MBR rather than GPT, or the firmware path is uncertain, stop and use the matching boot manual. Applying GPT bootcode to a different scheme is not recovery.

Verify the root storage before declaring success

Once GPT and the relevant boot path are intact, test the storage layer read-only where possible. For UFS, identify the filesystem with fstyp and run the appropriate check without casually accepting destructive repairs. For ZFS, use zpool import to inspect available pools and their status; do not force-import or upgrade the pool during boot repair.

Compare /etc/fstab identifiers with the recovered GPT labels. A perfect loader can still stop at mountroot> when a label changed or the root filesystem is damaged. Conversely, a healthy root filesystem does not help firmware locate a missing EFI loader.

Unmount the ESP cleanly, remove rescue media, and perform a console-observed boot. After success, capture a fresh metadata backup:

gpart backup ada0 > ada0.gpart.backup
efibootmgr -v

Store the backup off the repaired disk along with gpart show -p, pool status, and boot-entry output. A partition-table backup without its associated disk identity and date is easy to restore onto the wrong device later.

The recovery principle is strict separation: gpart recover repairs redundant GPT metadata; EFI repair restores files or firmware entries; BIOS repair writes PMBR and filesystem-specific bootcode; filesystem tools repair the root storage. Using the right tool at the wrong layer is how a boot incident becomes data loss.

Related:

Sources: