Fixing Disk Mounting and BFS Volume Check Issues on Haiku

A secondary volume that will not mount can fail at hardware detection, partition discovery, file-system recognition, or BFS consistency. Do not begin with repair. First identify the exact disk and partition, preserve readable data, and confirm that BFS—not another file system—is the component reporting the error.

Confirm device and partition identity

Use listdev for hardware and listusb for an external USB device, then open DriveSetup. Match capacity, model, connection, partition map, partition offset/size, and volume name. Never select a raw disk based only on changing /dev/disk/... numbering.

If the physical device is absent, this is a bus/driver/power/cable problem. Try another cable or port and capture syslog/device IDs. A file-system checker cannot repair a disk the kernel cannot read reliably.

In DriveSetup, expand the disk and identify the partition’s file-system type and mount state. Haiku’s guide notes that only BFS provides full attributes and queries. NTFS, FAT, ext, and other formats have different support and repair tools; do not run BFS repair against them.

Attempt a normal mount and save the error

Use DriveSetup or Deskbar’s Mount menu to mount the selected partition. Record the complete error and /var/log/syslog entries. If it mounts read-only, copy important files before attempting any modification.

Do not format or initialize the partition to “make it mount.” DriveSetup warns those operations destroy data. Do not change the partition map when the existing partition is visible but its file system is damaged.

If the volume mounts and files are readable, back up file data and attributes with a Haiku-aware method. A generic copy to a non-BFS volume may not preserve typed attributes and indexes. Keep an image of failing media when recovery value justifies it.

Run the current check-only command

Haiku’s current checkfs source documents -c/--check-only as the non-modifying mode:

checkfs -c /VolumeName

It also accepts a device path. Run checkfs --help on the installed revision and use the exact mount point or partition from DriveSetup. Capture the full output. Check-only establishes whether the disk system supports checking in the current mounted/unmounted state and reports errors without requesting modifications.

This corrects a dangerous outdated recipe: current checkfs does not document -r for repair. Do not copy repair flags from another operating system or an old forum post.

Repair only after backup

In the current implementation, omitting -c requests repair:

checkfs /dev/disk/.../partition

Prefer an unmounted secondary volume so applications cannot write while repair runs. The tool queries whether the file-system implementation supports repair mounted or unmounted and refuses unsupported combinations. Follow its error instead of forcing access around it.

Repair can remove or alter structures it cannot reconcile. Work from an image when data is irreplaceable, keep power stable, and do not interrupt the operation. For a failing physical disk, repeated scanning may worsen recovery; clone it first with appropriate hardware-recovery tools from a capable environment.

After repair, mount the volume, inspect representative files and attributes, and query indexed metadata. lsindex can enumerate volume indexes, but presence alone does not prove every index entry is correct. Rebuild/regenerate derived indexes only with BFS-aware tooling and after preserving evidence.

Distinguish corruption from hardware failure

A one-time inconsistency after power loss is different from errors recurring after a clean repair. Repeated read errors, disconnects, changing capacity, I/O timeouts, or fresh corruption point toward cable, enclosure, controller, power, or media failure.

Check syslog across the entire event, not only checkfs output. Test another known cable/port/enclosure where applicable. Use the drive vendor’s diagnostics or another OS’s hardware health tools without allowing them to “repair” BFS structures they do not understand.

Do not keep the only backup on another partition of the same physical disk. Once recovered, replace suspect hardware and restore onto a verified BFS volume.

Report a reproducible BFS defect

If hardware is stable and current Haiku reproduces the corruption, save revision/architecture, partition map, BFS block size, exact operations before failure, syslog, check-only output, and whether the volume was cleanly unmounted. A sanitized image or minimal reproducer may help file-system developers.

Never attach an image containing private data publicly. Ask maintainers for a secure sharing path or construct a small test image. State whether failure is mount, check, repair, index query, or data read; those enter different BFS code paths.

The safe order is detection, identity, mount evidence, backup/image, checkfs -c, then repair without -c only when acceptable. This prevents a recoverable mount problem from becoming unnecessary destructive work.

Related:

Sources: