CockroachDB out of memory: sys_rss, --cache, --max-sql-memory, and the OOM killer

A CockroachDB node disappears. No graceful shutdown, no drain sequence, no error in the SQL layer. The process is gone, and dmesg shows the kernel OOM killer selected it. Or in Kubernetes, the pod restarts with reason OOMKilled.

The root cause is almost always a mismatch between what CockroachDB thinks it can allocate and what the container or host actually allows. CockroachDB partitions its memory into two manually-sized pools: the Pebble block cache (--cache) and the SQL execution budget (--max-sql-memory). The Go garbage collector only manages the Go heap. CGo allocations, primarily the Pebble block cache and memtables, are manually managed. When the sum of these pools plus runtime overhead exceeds the container or host limit, the OOM killer intervenes.

The SQL error 53200 (“memory budget exceeded”) is the early warning. It fires when --max-sql-memory is exhausted, before the process itself is killed. If you see a burst of 53200 errors followed by a process termination, the diagnosis is straightforward. The harder cases are silent: CGo memory grows steadily, RSS climbs, and the first visible symptom is the OOM kill itself.

What this means

CockroachDB’s memory model has three distinct layers tracked by separate metrics:

• Go heap (sys_go_allocbytes): SQL execution buffers, connection state, metadata, goroutine stacks. Managed by the Go GC.
• CGo allocations (sys_cgo_allocbytes): primarily the Pebble block cache and memtables. Manually managed, not subject to Go GC.
• Total RSS (sys_rss): everything, including Go runtime overhead, memory-mapped files, and resident shared libraries.

The critical diagnostic question is which layer is growing. If sys_cgo_allocbytes grows while sys_go_allocbytes stays flat, the storage engine is the consumer. If sys_go_allocbytes grows, SQL execution is the consumer. If both are stable but RSS keeps climbing, the overhead (Go runtime, page cache, or a memory leak outside both accounting systems) is the problem.

The official sizing constraint is:

--cache + --max-sql-memory + --max-tsdb-memory <= 75% of available memory

The remaining 25% covers the Go runtime, OS page cache, and burst allocations. RSS should stay below 75% of the available memory, whether that is host RAM or a container cgroup limit, to leave headroom.

flowchart TD
    A["--cache (CGo: Pebble block cache)"] --> D["sys_rss"]
    B["--max-sql-memory (Go heap: SQL buffers)"] --> D
    C["Go runtime + Raft + OS page cache"] --> D
    D --> E{"RSS approaches limit"}
    E --> F["Go GC runs harder: sys_gc_pause_ns climbs"]
    F --> G["53200: SQL memory budget exceeded"]
    F --> H["GC pauses spike: Raft liveness at risk"]
    E --> I["RSS exceeds cgroup or host limit"]
    I --> J["OOM killer terminates cockroach"]

Common causes

Quick checks

# Check RSS against the container or host limit
curl -s http://localhost:8080/_status/vars | grep -E 'sys_(rss|go_allocbytes|cgo_allocbytes)'

# Check SQL memory budget utilization
curl -s http://localhost:8080/_status/vars | grep sql_mem_root_current

# Check Go GC pause duration (cumulative counter) and frequency
curl -s http://localhost:8080/_status/vars | grep -E 'sys_gc_(pause|count)'

# Check SQL failure counter (total failures, not broken down by code)
curl -s http://localhost:8080/_status/vars | grep sql_failure_count

# Check the process flags to verify --cache and --max-sql-memory values
ps -p $(pgrep -x cockroach) -o args=

# Check OS-level RSS
cat /proc/$(pgrep -x cockroach)/status | grep VmRSS

# Check OOM killer history
dmesg -T | grep -i "out of memory\|oom kill\|killed process"

# Check container memory limit (cgroups v2, then v1 fallback)
cat /sys/fs/cgroup/memory.max 2>/dev/null || cat /sys/fs/cgroup/memory/memory.limit_in_bytes

# Check goroutine count (each has a small starting stack)
curl -s http://localhost:8080/_status/vars | grep sys_goroutines

To confirm 53200 errors specifically, grep the CockroachDB logs rather than relying on the aggregate sql_failure_count counter:

# Check for 53200 errors in logs
grep -r "53200\|memory budget exceeded" /var/lib/cockroach/logs/ 2>/dev/null || \
  cockroach sql --insecure --execute "SELECT count(*) FROM [SHOW CLUSTER STATEMENTS] WHERE error = '53200'"

How to diagnose it

1. Determine which memory layer is growing. Pull sys_rss, sys_go_allocbytes, and sys_cgo_allocbytes over a time window that includes the crash. If you only have post-crash data, check monitoring history for the trend leading up to the event.

2. Check the sizing arithmetic. Identify the effective --cache, --max-sql-memory, and --max-tsdb-memory values from the process flags. Compute --cache + --max-sql-memory + --max-tsdb-memory. Compare against 75% of the actual memory available to the process (container limit, not host RAM).

3. Verify cgroup detection. In container environments, CockroachDB may detect host RAM instead of the container limit. This is common with cgroups v2, where memory.max can report the string “max” inside child cgroups that are actually constrained by a parent. If --cache=25% and --max-sql-memory=25% resolve against host RAM instead of the pod limit, the process will be OOM killed.

4. Check for 53200 errors preceding the crash. A burst of 53200 errors means the SQL memory budget was exhausted first. This points to memory-intensive queries rather than a cache sizing problem. Cross-reference with sql_mem_root_current to confirm the SQL budget was near its ceiling.

5. Compare CGo allocated against the configured cache. Under normal conditions, CGo allocated should not exceed the --cache size, and CGo total should not exceed it by more than 15%. If CGo allocated significantly exceeds the cache, the storage engine may be leaking memory through the Pebble block cache.

6. Check the overhead gap. Compute sys_rss minus the sum of Go total (sys_go_totalbytes) and CGo total (sys_cgo_totalbytes). A gap exceeding 100 MB suggests unaccounted memory growth outside both accounting systems. A growing gap indicates the overhead is increasing over time.

7. Review GC behavior. sys_gc_pause_ns is a cumulative counter. Divide the delta between scrapes by the delta in sys_gc_count over the same window to get the average pause per GC cycle. Average pauses exceeding 500ms indicate significant memory pressure. Sustained GC pauses approaching the 3-second liveness heartbeat interval (with a 6-second liveness expiry) risk Raft leader changes and node liveness loss before the OOM kill even happens, creating a pattern where the node oscillates between alive and dead.

Metrics and signals to monitor

Fixes

Reduce –cache or –max-sql-memory

If the sizing arithmetic does not fit within the container or host limit, reduce one or both values. The constraint is --cache + --max-sql-memory + --max-tsdb-memory <= 75% of available memory. Reducing --cache hurts read performance (more cache misses, higher KV read latency, more disk I/O). Reducing --max-sql-memory causes large queries to spill to disk sooner or be rejected with 53200 errors.

Both reductions have real performance cost. The safer approach is to increase the container or host memory if the workload requires the current cache and SQL memory sizes.

Set explicit byte values in containers

Do not rely on percentage-based --cache and --max-sql-memory values in containerized deployments. CockroachDB’s cgroup memory detection is unreliable, particularly with cgroups v2, where memory.max can report the string “max” inside child cgroups that are constrained by a parent. Set explicit byte values instead:

cockroach start --cache=4GiB --max-sql-memory=4GiB ...

This ensures the values resolve to what you intend regardless of cgroup detection behavior.

If you use systemd unit files with percentage values, the % character must be escaped as %%.

Cancel memory-intensive queries

If sql_mem_root_current is the culprit, identify and cancel the consuming query. Use SHOW CLUSTER SESSIONS to find active sessions and their current queries, and CANCEL QUERY to terminate them. Large sorts, hash joins on big tables, and full table scans are common causes.

The SQL memory budget is per-node, not per-query. A single large query can starve all others of memory. After cancelling, investigate the query plan to determine whether an index addition or query rewrite can reduce memory consumption.

Address CGo / Pebble cache growth

If sys_cgo_allocbytes grows while sys_go_allocbytes is flat, the storage engine is the consumer. Under normal conditions, CGo allocated should not exceed the configured --cache. Known issues with Pebble cache entry finalization can cause CGo memory to grow without being reclaimed, because the CGo memory is not subject to Go garbage collection.

If this pattern appears, check whether a newer CockroachDB version includes a fix for the leak. Reducing --cache temporarily limits the ceiling but does not fix the underlying issue.

Rate-limit backups and bulk operations

Backups, RESTORE, IMPORT, and debug zip generation can cause memory spikes that push an already-tight budget over the limit. If the OOM coincides with one of these operations, schedule them during low-traffic periods and ensure the memory budget has headroom beyond what steady-state traffic requires.

Prevention

• Size correctly from the start. Use --cache + --max-sql-memory + --max-tsdb-memory <= 75% of available memory. The remaining 25% covers the Go runtime, OS page cache, and burst allocations. Keep RSS below 75% of the limit.
• Set explicit byte values in containers. Do not rely on percentage-based flags. Cgroup detection is unreliable, especially with cgroups v2.
• Monitor the three memory layers separately. Track sys_rss, sys_go_allocbytes, and sys_cgo_allocbytes independently. A single RSS alert without the breakdown tells you something is wrong but not what.
• Alert on 53200 errors. A burst of 53200 errors is the SQL-layer warning that precedes most OOM kills. Set up log-based alerting since sql_failure_count does not break down by error code.
• Watch GC pause duration. Average per-cycle pauses above 500ms indicate memory pressure before RSS reaches the hard limit.
• Set Transparent Huge Pages to madvise. THP set to always can cause increased memory usage. CockroachDB recommends madvise.
• Account for connection overhead. Each connection consumes a goroutine and session memory. Connection storms after failover can push an already-tight memory budget over the edge.

How Netdata helps

• Per-second sys_rss, sys_go_allocbytes, and sys_cgo_allocbytes tracking lets you see which memory layer is growing before the OOM kill, not just after. Per-second resolution captures spikes that 15-30 second scrape intervals miss.
• sql_mem_root_current correlated with sql_failure_count shows whether SQL budget exhaustion precedes the RSS climb, distinguishing SQL-driven memory growth from cache or runtime overhead.
• GC pause metrics (sys_gc_pause_ns, sys_gc_count) alongside node liveness signals reveal whether memory pressure is causing GC pauses that threaten Raft liveness before the OOM killer fires.
• Container-aware memory monitoring correlates CockroachDB’s own RSS reporting with the cgroup memory limit, making cgroup mis-detection visible as a divergence between what CockroachDB thinks it can allocate and what the kernel allows.

Netdata’s database monitoring brings these signals together with per-second metrics.

Related guides

• CockroachDB clock_offset_meannanos high: catching clock drift before self-termination
• CockroachDB clock skew cascade: how shared NTP drift causes quorum loss
• CockroachDB clock synchronization error: this node is more than 500ms away from at least half of the known nodes
• CockroachDB compaction backlog growing: when Pebble can’t keep pace with writes
• CockroachDB context deadline exceeded: timeouts, slow ranges, and overload
• CockroachDB detecting hot ranges: per-range QPS, CPU asymmetry, and the Hot Ranges page
• CockroachDB disk space running out: capacity_available trends and the 20% rule
• CockroachDB disk stall detected: storage_disk_stalled and node self-termination
• CockroachDB hot range bottleneck: one leaseholder saturated while the cluster idles
• CockroachDB intent accumulation cascade: abandoned transactions and intentcount growth
• CockroachDB storage_l0_sublevels climbing: the earliest warning of write stalls
• CockroachDB LSM compaction death spiral: L0 sublevels, read amplification, and write stalls