FreeBSD 12 – Common Problem 013 – Swap Exhaustion Causes Process Kills

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

Services are killed or become unresponsive under load due to memory exhaustion.

Environment & Reproduction

High-concurrency workloads on undersized VM instances trigger rapid swap depletion.

Root Cause Analysis

Memory overcommit and insufficient swap allocation push kernel into aggressive paging.

Quick Triage

Measure immediate memory and swap state.

swapinfo -h
top -o size
vmstat -z

Step-by-Step Diagnosis

Locate top consumers and verify paging trend.

procstat -r $(pgrep -f yourservice | head -n1)
vmstat 1 10
sysctl vm.swap_enabled

Solution – Primary Fix

Increase swap capacity and cap service memory usage.

truncate -s 4G /usr/swap0
chmod 0600 /usr/swap0 && swapon /usr/swap0
echo 'md99 none swap sw,file=/usr/swap0,late 0 0' >> /etc/fstab

Solution – Alternative Approaches

Scale vertically or split workload into jails/hosts with explicit resource limits.

Verification & Acceptance Criteria

No OOM-like kills, swap stabilizes, and latency returns within SLO thresholds.

Rollback Plan

Deactivate temporary swap file and revert memory limit changes if side effects occur.

Prevention & Hardening

Capacity-plan using peak telemetry and enforce per-service memory ceilings.

Related Errors & Cross-Refs

`out of swap space`, abrupt daemon restarts, heavy paging observed in `vmstat`.

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

View all freebsd-12 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

FreeBSD performance tuning handbook, `swapinfo(8)`, `vmstat(8)`.