FreeBSD 14 – ZFS Snapshot Pruning Fails and Space Exhausts – Retention Repair

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

Pool free space drops unexpectedly due to unpruned snapshots and backups failing.

Environment & Reproduction

Appears when retention jobs fail silently after naming or permission changes.

zfs list -t snapshot | wc -l
zpool list

Root Cause Analysis

Snapshot lifecycle automation no longer matches target datasets or naming patterns.

Quick Triage

Identify oldest/largest snapshot trees and paused cleanup jobs.

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

Step-by-Step Diagnosis

Audit pruning scripts, cron schedule, and permission context for deletion operations.

crontab -l
grep -R 'zfs destroy' /usr/local/sbin /root 2>/dev/null

Solution – Primary Fix

Repair retention logic and safely remove stale snapshots in controlled batches.

zfs list -t snapshot -o name -s creation | head -n 20 | xargs -n1 zfs destroy -v
zpool list

Solution – Alternative Approaches

Adopt sanoid/syncoid or equivalent policy-driven snapshot management tooling.

Verification & Acceptance Criteria

Free space recovers and retention jobs run on schedule without errors.

zpool list
grep -i zfs /var/log/cron 2>/dev/null | tail -n 20

Rollback Plan

Restore required points-in-time from replication target if over-pruning occurred.

Prevention & Hardening

Define explicit snapshot TTL policies and alert on growth anomalies.

Related Errors & Cross-Refs

cannot destroy snapshot: dataset is busy, pool near capacity, ENOSPC.

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

OpenZFS snapshot lifecycle and retention strategy guidance.