FreeBSD 14 – system becomes unstable from swap exhaustion – Fix & Prevention

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

Host latency spikes and services fail when swap is exhausted, sometimes ending in OOM kills.

Environment & Reproduction

Seen on memory-constrained VMs or after workload growth without capacity updates.

swapinfo -h
top -o res
vmstat -z

Root Cause Analysis

Resident memory demand exceeds RAM and configured swap, causing heavy paging and process starvation.

Quick Triage

Identify top consumers and stop runaway processes safely.

procstat -v $(pgrep -n java)
ps auxww | sort -k4 -nr | head
service app status

Step-by-Step Diagnosis

Correlate memory pressure with workload events and daemon behavior.

systat -vmstat 1
swapinfo -k
vmstat 1

Solution – Primary Fix

Add swap capacity and tune application memory limits.

truncate -s 8G /usr/swap0
chmod 600 /usr/swap0
mdconfig -a -t vnode -f /usr/swap0 -u 0
swapon /dev/md0

Solution – Alternative Approaches

Scale vertically, shard workload, or enforce per-service memory capping with jails and rctl.

Verification & Acceptance Criteria

Swap utilization stabilizes and service latency returns to expected baseline.

swapinfo -h
top -S
service app restart

Rollback Plan

Disable temporary swapfile if it causes disk pressure or operational risk.

swapoff /dev/md0
mdconfig -d -u 0
rm -f /usr/swap0

Prevention & Hardening

Set memory alerts, right-size instances, and test peak load behavior quarterly.

Related Errors & Cross-Refs

Related to ZFS ARC pressure, runaway application leaks, and queue backlogs.

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

rctl(8), swapoff(8), and FreeBSD memory management documentation.