FreeBSD 15 – ZFS Pool Near Capacity Causes Write Stalls – Space Reclamation Plan

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

Application writes stall and latency spikes when pool free space drops to unsafe thresholds.

Environment & Reproduction

High snapshot churn and retained datasets consume available pool capacity rapidly.

zpool list
zfs list -o name,used,avail,mountpoint

Root Cause Analysis

Fragmentation and metadata overhead increase sharply as pools approach full utilization.

Quick Triage

Identify largest consumers and snapshot growth vectors immediately.

zfs list -o name,used -s used | tail -n 20
zfs list -t snapshot -o name,used -s used | tail -n 20

Step-by-Step Diagnosis

Trace dataset growth and scrub health to rule out hidden errors.

zpool status
zpool iostat -v 5 3

Solution – Primary Fix

Delete stale snapshots, expand pool where possible, and rebalance hot datasets.

zfs destroy -r zroot/data@old-snap
zpool add zroot 
zpool scrub zroot

Solution – Alternative Approaches

Apply quotas/reservations and tier archival data to slower, larger pools.

Verification & Acceptance Criteria

Pool free space returns to policy floor and write latency normalizes.

zpool list
zpool iostat -v 1 5

Rollback Plan

Suspend nonessential data movement if expansion introduces unexpected resilver risk.

Prevention & Hardening

Set alerting on pool capacity and snapshot age with automatic retention cleanup.

Related Errors & Cross-Refs

pool is full, write failed, dataset out of space.

Related tutorial: View the step-by-step tutorial for freebsd-15.

View all freebsd-15 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

zpool(8), zfs(8), and capacity planning guidance for production ZFS.