When a Simple Drive Swap Triggers a ZFS Protective Lockout
1. What FreeNAS Is Telling You (Even When the GUI Doesn’t Say It Clearly)
On FreeNAS (and legacy FreeBSD-based systems), a pool that refuses to mount after a drive replacement is almost never a filesystem failure — it is ZFS protecting your data from a metadata mismatch.
You may see symptoms like:
- The pool shows DEGRADED or UNAVAIL
- The replacement disk appears ONLINE
- The mount action reports “cannot import pool”, “one or more devices missing”, or “incorrect GUID”
- Your data is still intact, but ZFS refuses to commit to a layout it cannot trust
This is normal. This is by design.
And it almost always means the system metadata (vdev GUIDs, TXG, pool transaction map) no longer agree.
2. Why This Happens on FreeNAS
Unlike hardware RAID, ZFS uses a strict, baked-in identity system:
- Pool GUIDs identify the whole storage group
- Vdev GUIDs identify each disk or mirror
- TXG (transaction groups) track the last clean write boundaries
A replacement disk that appears healthy can still break identity because:
- The new disk inherited stale or foreign ZFS headers
- A failed disk was replaced after the pool had already drifted out of sync
- A power event occurred during resilver, leaving mixed TXG states
- The controller or HBA changed the enumerated order (less common, but possible)
When metadata diverges, FreeNAS protects the pool by refusing the mount.
3. What You SHOULD NOT Do
This is where most data loss happens.
If a FreeNAS pool will not mount:
Do NOT:
- Run zpool clear, export/import -f, or “auto-import” retries
- Attempt a GUI “repair” or “replace” again
- Detach the failed disk(s)
- Recreate the pool
- Let the system try to finish a resilver it cannot validate
These actions overwrite original vdev order, destroy historical TXG boundaries, or cause permanent pool collapse.
4. Safe Diagnostic Steps (Non-Destructive)
You can safely gather this information without modifying the pool:
- Run: zpool import
- Gather GUID information: zdb -l /dev/daX
- Confirm whether the replacement disk has inherited foreign ZFS labels
- Capture system logs: dmesg | grep ZFS
- Take no write actions until identity is confirmed
If the pool shows mismatched GUIDs, missing TXG, or vdev disagreement, imaging and reconstruction is required.
5. What This Means for Your Data
- Your data is usually intact, but ZFS is preventing a metadata-destructive mount
- The replacement disk may be healthy physically but wrong logically
- Re-silvers or force-imports can rewrite pool topology, causing irreversible corruption
- With imaging and GUID-matching, pools can be reconstructed safely offline
- FreeNAS failures like this are recoverable as long as the original metadata is preserved
Diagnostic Overview
- System: FreeNAS / FreeBSD (ZFS)
- Observed State: Pool Unavailable or Cannot Import After Drive Replacement
- Likely Cause: Vdev GUID mismatch, stale ZFS labels, or TXG identity drift during replacement
- Do NOT: Force import, detach disks, run repair, or retry replacement actions
- Recommended Action: Capture ZFS headers, compare GUIDs, image disks, reconstruct topology offline
Back to RAID Controller & Systems Triage