ZFS Snapshot Growth Consumes Pool Capacity

📖 ~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

Unbounded snapshot retention can fill pools and block writes even when active datasets appear modest.

Environment & Reproduction

zpool capacity climbs steadily, and deleting files does not recover expected free space.

Root Cause Analysis

Systems using frequent automated snapshots without enforced retention policies.

Quick Triage

Understanding of replication dependencies and backup windows before deleting snapshots.

Step-by-Step Diagnosis

[image_ref: 0] Run zfs list -t snapshot -o name,used,creation -s creation; zpool list; zfs get usedbysnapshots -r poolname.

Solution – Primary Fix

[image_ref: 1] Confirm retention scripts, cron entries, and replication holds are documented and current.

Solution – Alternative Approaches

Delete obsolete snapshots in controlled batches, preserve replication-required checkpoints, and enforce retention via scheduled scripts.

Verification & Acceptance Criteria

Pool free space recovers and usedbysnapshots trends downward after cleanup.

Rollback Plan

Restore data from backup if required snapshots were removed prematurely.

Prevention & Hardening

Define explicit snapshot retention by dataset criticality and monitor pool capacity projections.

Related Errors & Cross-Refs

Escalate when holds from replication tools block deletion and threaten outage timelines.

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

View all freebsd-14 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

zfs(8), zpool(8), periodic(8), FreeBSD ZFS operations guidance.