FreeBSD 15: ZFS ARC pressure triggers swap storms

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

Interactive latency rises while swap IO dominates, degrading service response and throughput.

Environment & Reproduction

Appears under mixed filesystem and application memory demand on constrained hosts.

Root Cause Analysis

ARC growth and competing process memory pressure force excessive paging under peak load.

Quick Triage

Confirm memory profile, identify top consumers, and review current ARC sizing parameters.

Step-by-Step Diagnosis

Correlate ARC stats, swap activity, and process footprints during high utilization windows.

Solution – Primary Fix

Tune ARC bounds and rebalance workload memory allocation to prevent aggressive swapping.

Solution – Alternative Approaches

Scale memory capacity or segregate memory-heavy services from storage-intensive hosts.

Verification & Acceptance Criteria

Swap rates remain low, latency recovers, and sustained load no longer triggers memory thrash.

Rollback Plan

Restore previous kernel tunables and service placement if tuning impacts cache hit rates.

Prevention & Hardening

Adopt capacity baselines, ARC observability dashboards, and proactive scaling thresholds.

Related Errors & Cross-Refs

Often intersects with database cache oversubscription and VM ballooning behavior.

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

OpenZFS tuning docs, FreeBSD performance handbook, and vmstat-based troubleshooting guides.