When migrating home lab storage or enterprise virtualization from FreeBSD-based TrueNAS CORE to Debian-based TrueNAS SCALE in 2026, administrators inevitably encounter a brutal operational surprise: Docker containers, Kubernetes pods, and VM instances randomly terminating with Linux OOM (Out-of-Memory) error codes. The culprit is not faulty application code—it is the architectural collision between OpenZFS Adaptive Replacement Cache (ARC) memory management and the Linux kernel’s virtual memory subsystem.
- Default Memory Allocation: TrueNAS SCALE defaults OpenZFS ARC to claim up to 50% of total host RAM, but memory pressure reclamation latency frequently lags behind burst container allocations.
- The OOM Killer Trap: When heavy container workloads demand immediate heap memory, the Linux kernel invokes
oom_killagainst high-memory userspace processes before ZFS ARC completes its shrink cycle. - Surgical Tuning Target: Hardcoding
zfs_arc_maxto exactly 65–70% of available free RAM after subtracting base VM and container reservations completely eliminates memory thrashing and prevents system panics.
Why Does TrueNAS SCALE Run Out of RAM? ZFS ARC vs. Linux Page Cache
TrueNAS SCALE experiences Out-of-Memory crashes because Linux kernel memory shrinkers operate asynchronously from OpenZFS ARC. While FreeBSD treated ZFS ARC as native kernel memory, the Linux kernel views OpenZFS ARC as an external slab cache. When memory pressure spikes, the Linux OOM killer fires in nanoseconds, killing user applications before ZFS ARC can evict dirty buffers.
In TrueNAS CORE, the FreeBSD VM subsystem maintained direct hooks into ZFS ARC memory eviction. In TrueNAS SCALE (built on the Linux kernel), OpenZFS runs as a kernel module that registers standard memory shrinkers. However, when an AI inference workload, a transcode stream, or a local database requests a 16GB allocation spike, the Linux kernel’s kswapd daemon evaluates memory pressure faster than ZFS ARC can prune its Most Recently Used (MRU) and Most Frequently Used (MFU) cache lists. The kernel panics, assumes a fatal memory exhaustion state, and terminates high-memory processes.
| Host RAM Tier | Default SCALE ARC Cap (50%) | Recommended zfs_arc_max | Reserved Host & App Overhead |
|---|---|---|---|
| 32 GB DDR4/DDR5 | 16 GB | 14 GB (15,032,385,536 Bytes) | 18 GB (Docker + TrueNAS Middleware) |
| 64 GB ECC DDR5 | 32 GB | 36 GB (38,654,705,664 Bytes) | 28 GB (2x Virtual Machines + Apps) |
| 128 GB ECC Registered | 64 GB | 80 GB (85,899,345,920 Bytes) | 48 GB (Local LLM + Kubernetes Cluster) |
How Do You Calculate and Set zfs_arc_max in TrueNAS SCALE?
To safely size zfs_arc_max, calculate: Host RAM – (Base TrueNAS Middleware [4GB] + Sum of Dedicated VM RAM + Container Buffers) = Target ARC Bytes. Set this persistently in TrueNAS SCALE under System Settings > Advanced > Sysctl using the variable vfs.zfs.arc.max.
Executing live changes without rebooting is simple via the TrueNAS SCALE bash shell. For example, to constrain ARC to 32GB on a 64GB host:
# Calculate: 32 * 1024 * 1024 * 1024 = 34359738368
echo 34359738368 > /sys/module/zfs/parameters/zfs_arc_max
# Verify active setting
arc_summary | grep -E "ARC size|Target size"Frequently Asked Questions: TrueNAS SCALE ZFS Memory Sizing
Why does TrueNAS SCALE kill apps when RAM usage hits 90%?
TrueNAS SCALE uses the Linux kernel’s Out-Of-Memory (OOM) killer. Because OpenZFS ARC memory eviction is slower than memory allocation bursts from Docker or VMs, the Linux kernel kills the highest-memory userspace process to prevent an immediate system crash.
What is the default ZFS ARC limit in TrueNAS SCALE?
By default, TrueNAS SCALE sets zfs_arc_max to 50% of physical installed RAM, unlike TrueNAS CORE which allocated up to 90% of memory to ZFS ARC.
How do you make zfs_arc_max persistent across TrueNAS reboots?
Navigate to TrueNAS SCALE Web UI > System Settings > Advanced > Sysctl, click Add, and enter vfs.zfs.arc.max with your calculated byte value.