ZFS Refuses the Import Because Metadata No Longer Matches Reality
1. What TrueNAS SCALE Is Really Telling You (Even If the GUI Doesn’t Say It Clearly)
On TrueNAS SCALE (Linux + OpenZFS), a pool that refuses to import after a drive replacement is almost never a disk failure — it’s ZFS refusing to accept metadata that doesn’t agree.
You may see:
- Pool state: UNAVAIL, FAULTED, or cannot import
- GUI reports a disk as ONLINE, but pool cannot mount
- System logs show “vdev mismatch”, “incorrect GUID”, or “missing device”
- Import attempts say:
“One or more devices missing or invalid”
“Pool may be in use on another system”
“Insufficient replicas”
This is ZFS protecting your data from a potentially catastrophic wrong-topology import.
Your data is almost always still there — ZFS is just not willing to guess.
2. Why This Happens on TrueNAS SCALE
SCALE behaves differently than FreeNAS/CORE due to Linux+systemd timing and newer OpenZFS behavior. Metadata disagreement can occur when:
- The new disk carries stale or foreign ZFS labels
- The previous disk had incomplete writes when failing
- The pool had mixed TXG (transaction group) states when the swap occurred
- Hotplug events caused mismatched device enumeration
- Linux detected disks in a different order than OpenZFS expected
- The system attempted a resilver but aborted mid-TXG
SCALE is stricter than CORE:
If GUIDs, TXGs, or topology maps don’t match perfectly, SCALE refuses pool import entirely.
3. What You SHOULD NOT Do
These actions permanently destroy pool identity:
Do NOT:
- Run zpool import -f
- Run zpool clear, detach, or replace again
- Use GUI “force import”
- Attempt “auto-import” retries
- Recreate the pool
- Let SCALE retry a resilver on confused topology
Any forced import writes updated headers and TXGs — and once that happens, the original identity is gone.
4. Safe Diagnostic Steps (Non-Destructive)
These steps are safe and do not modify metadata:
- Check importability: zpool import
- Inspect each disk’s ZFS labels: zdb -l /dev/disk/by-id/…
- Capture OpenZFS warnings from SCALE: journalctl -xe | grep -Ei ‘zfs|vdev’
- Compare vdev GUIDs and check for foreign labels.
If any disk has mismatched GUID or inconsistent TXG, the pool cannot be safely imported.
Recovery requires imaging and reconstructing topology from consistent metadata.
5. What This Means for Your Data
- The disks are often healthy — the identity is what’s broken
- ZFS is refusing to import because TXGs or GUIDs don’t match the expected pool state
- A forced import can destroy historical consistency and collapse the pool
- Given clean disk images, the pool can be reconstructed offline
- Most SCALE pool failures like this are fully recoverable if metadata is preserved
Diagnostic Overview
- System: TrueNAS SCALE (Linux + OpenZFS)
- Observed State: Pool Cannot Import After Drive Replacement
- Likely Cause: Vdev GUID mismatch, foreign ZFS labels, or TXG divergence during replacement
- Do NOT: Force import, clear, detach, or allow resilvering on a mismatched topology
- Recommended Action: Capture ZFS labels, compare GUIDs and TXGs, image disks, reconstruct pool offline
Back to RAID Controller & Systems Triage