Swap Exhaustion Triggers OOM-Like Instability

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

Swap exhaustion degrades responsiveness and can force process termination under pressure.

Environment & Reproduction

High paging, stalled interactive sessions, and frequent service timeouts under workload spikes.

Root Cause Analysis

Compute, database, and build hosts with insufficient RAM-to-workload sizing.

Quick Triage

Privilege to adjust swap devices and restart memory-intensive services during maintenance.

Step-by-Step Diagnosis

[image_ref: 0] Run top -aSH; vmstat -z; swapinfo -h; sysctl vm.swap_total_enabled; systat -vmstat 1.

Solution – Primary Fix

[image_ref: 1] Verify swap entries in /etc/fstab and ensure no failed swap partitions at boot.

Solution – Alternative Approaches

Add or expand swap devices, reduce peak memory consumers, and tune service limits. On ZFS systems, validate ARC sizing if memory pressure is sustained.

Verification & Acceptance Criteria

Swap usage stabilizes below alert thresholds and application latency returns to normal.

Rollback Plan

Revert temporary tunings that reduce cache effectiveness once capacity changes are complete.

Prevention & Hardening

Forecast memory demand and set alerting on swap growth rate, not only absolute use.

Related Errors & Cross-Refs

Escalate when pressure originates from kernel leaks, driver faults, or unbounded process growth.

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

top(1), swapinfo(8), vmstat(8), sysctl(8), FreeBSD performance tuning docs.