Apache Pulsar OutOfDirectMemoryError: the off-heap crash JVM heap dashboards never show

The broker is down. Your JVM dashboard shows heap at 55%, GC pauses normal, no heap OOM anywhere. Then someone opens the broker log and finds the real cause:

io.netty.util.internal.OutOfDirectMemoryError: failed to allocate 16777216 byte(s) of direct memory (used: ..., max: ...)

or the plainer JDK variant, java.lang.OutOfMemoryError: Direct buffer memory. The process may have exited deliberately: PulsarByteBufAllocator catches the allocation failure and, when -Dpulsar.allocator.exit_on_oom=true is set (the shipped default is false, with pulsar.allocator.out_of_memory_policy=FallbackToHeap), kills the JVM immediately. Independently, the broker shuts itself down when it receives the direct-memory OOM unless skipBrokerShutdownOnOOM=true. Either way, the broker is dead in the part your heap monitoring was not watching.

This is one of the most common surprise failures in Pulsar operations. Everything Netty touches, which is everything the broker does on the network, allocates off-heap. Heap dashboards cannot see it. This article covers how to confirm the diagnosis in minutes, what actually consumes direct memory in a broker, and how to size and monitor the off-heap space so it stops being a blind spot.

What this means

The JVM splits memory into the managed heap (what -Xmx controls, what GC cleans, what most dashboards graph) and everything else. “Direct” or off-heap memory is allocated outside the heap via ByteBuffer.allocateDirect and Netty’s own allocator. It is not garbage collected in the normal sense and does not appear in heap metrics.

A Pulsar broker is heavy on direct memory by design:

• Netty channel buffers. Every producer, consumer, broker-to-bookie, and replication connection carries direct-memory read and write buffers. Zero-copy networking is the whole point.
• The managed ledger cache. Recently written entries are cached off-heap so tailing consumers read from broker memory instead of hitting bookies.
• Messages in flight. Entries being read from bookies and dispatched to consumers occupy direct buffers until they are written to the socket and released.

Direct memory is bounded by -XX:MaxDirectMemorySize. If that flag is not set, the JVM default is approximately -Xmx. The Pulsar broker default configuration is commonly -Xmx2g with -XX:MaxDirectMemorySize=4g. Bookie scripts ship tighter defaults (-Xms2g -Xmx2g -XX:MaxDirectMemorySize=2g), which is easily exhausted under load. Check what your deployment actually sets in pulsar_env.sh or bkenv.sh; do not assume the documented defaults survived your packaging.

The failure shape is a cliff, not a curve. The broker works normally until the allocator cannot satisfy one more buffer, then it either hangs waiting for allocation or dies with the OOM. There is no graceful degradation phase to catch with a latency alert.

flowchart TD
  A[Connection storm, large messages, or oversized cache] --> B[Direct buffer allocations accumulate]
  B --> C{Direct memory at MaxDirectMemorySize?}
  C -- no --> B
  C -- yes --> D[Netty allocation fails: OutOfDirectMemoryError]
  D --> E{exit_on_oom / shutdown policy}
  E -- exit --> F[JVM exits: broker down, bundles reassign]
  E -- no exit --> G[Broker alive but unable to serve I/O: zombie]
  F --> H[Client reconnect storm on surviving brokers]
  G --> H
  H --> A

Note the loop at the bottom. When the broker dies or goes zombie, its bundles reassign and thousands of clients reconnect to the surviving brokers. Those reconnections allocate fresh direct buffers on the survivors. One broker’s off-heap OOM can become the next broker’s off-heap OOM.

Common causes

Quick checks

All read-only. Run these on the affected broker host and against its endpoints.

# 1. Confirm the signature in the broker log
grep -E "OutOfDirectMemoryError|Direct buffer memory|Exiting JVM process for OOM" /var/log/pulsar/*.log | tail -20

# 2. Check whether the process is alive at all (zombie vs exited)
pgrep -af PulsarBroker

# 3. If alive but unresponsive: health check
curl -s -o /dev/null -w "%{http_code}\n" --max-time 5 http://localhost:8080/admin/v2/brokers/health

# 4. Compare RSS to heap. RSS far above -Xmx is the tell.
grep VmRSS /proc/$(pgrep -f PulsarBroker)/status
jcmd $(pgrep -f PulsarBroker) GC.heap_info | head -5

# 5. Read the actual direct buffer pool via JMX (this is the ground truth)
# If you have a JMX exporter: jvm_buffer_pool_used_bytes{pool="direct"}
# Otherwise check the configured limit on the running process:
jcmd $(pgrep -f PulsarBroker) VM.info | grep -i direct

# 6. Check connection pressure before the crash
curl -s http://localhost:8080/metrics | grep -E "pulsar_active_connections|pulsar_connection_(created|closed)"

# 7. Check managed ledger cache state
curl -s http://localhost:8080/metrics | grep pulsar_ml_cache

# 8. Netty allocator internals (fragmentation, active allocations)
curl -s http://localhost:8080/admin/v2/broker-stats/allocator-stats/default | head -40

# 9. Verify the actual JVM flags the broker runs with
jcmd $(pgrep -f PulsarBroker) VM.command_line | tr ' ' '\n' | grep -E "Xmx|MaxDirectMemorySize|exit_on_oom"

Two of these deserve emphasis. Check 4 is the fastest confirmation: if process RSS is 6 GB against a 2 GB heap and the log shows the direct-memory error, you are done diagnosing. Check 9 matters because many deployments run with MaxDirectMemorySize unset, in which case the ceiling silently equals -Xmx and the effective budget for Netty plus the ledger cache is much smaller than anyone assumed.

How to diagnose it

1. Confirm the error class. Grep the broker log for OutOfDirectMemoryError or Direct buffer memory. Also look for Exiting JVM process for OOM error: Direct buffer memory, which tells you PulsarByteBufAllocator deliberately exited the JVM. If neither is present and the broker simply hung, this article still applies, but keep heap OOM and GC death spiral as alternates.
2. Establish the ceiling. Pull the broker’s JVM flags. If -XX:MaxDirectMemorySize is absent, the limit defaults to roughly -Xmx. Write down the number; every later step compares usage against it.
3. Measure actual direct memory usage over time. Pulsar does not expose direct memory as a Prometheus metric. You need the JMX bean java.nio:type=BufferPool,name=direct (MemoryUsed / TotalCapacity), typically via a JMX exporter giving you jvm_buffer_pool_used_bytes{pool="direct"}. If you have no JMX pipeline, process RSS minus heap (VmRSS minus committed heap from GC.heap_info) is a usable proxy for off-heap growth.
4. Classify the growth pattern. Steady climb over days with flat traffic points to a leak (connections or buffers). A ramp that tracks connection count points to connection-driven allocation. A spike aligned with publish or catch-up read bursts points to workload-driven allocation. A plateau high from startup points to cache sizing.
5. Correlate with the driver. Overlay direct memory against pulsar_active_connections, pulsar_throughput_in/out, and pulsar_ml_cache_used_size. Whichever moves in lockstep with direct memory is your cause.
6. Check for a leak if nothing correlates. Created vs closed connection counters diverging means clients are not closing connections. Stable connections with growing allocator stats means buffers are retained; compare your Pulsar version against known buffer-leak fixes before tuning around it.
7. Decide: sizing fix, config fix, or version fix. Sizing: raise MaxDirectMemorySize with headroom. Config: shrink the cache or publish buffer. Version: upgrade if you are on a release with a known leak or missing backpressure fix.

Metrics and signals to monitor

Pulsar’s own /metrics endpoint exposes the managed ledger cache (pulsar_ml_cache_*) but not overall JVM direct memory. That gap is why this failure surprises people. Closing it requires the JMX exporter or an agent that reads the BufferPool MBean.

Fixes

Immediate: restore service

The broker that threw OutOfDirectMemoryError is functionally dead even if the PID exists. Restart it; it cannot allocate buffers for any I/O. If the allocator exited the JVM on its own, your supervisor has probably already restarted it. Watch the survivors during recovery: the client reconnect storm lands on them, and if their direct memory headroom was already thin, they can follow the first broker down. Stagger restarts if multiple brokers are affected.

Raise the ceiling, correctly

Set -XX:MaxDirectMemorySize explicitly in pulsar_env.sh; never rely on the implicit equals--Xmx default. Size it as the sum of what the broker legitimately needs: managed ledger cache plus publish buffer plus per-connection and in-flight buffers, with headroom on top. Then verify the whole thing fits in the container or host memory limit: heap + direct memory + JVM overhead must stay well under the cgroup limit, or the kernel OOM killer replaces this problem with a quieter one.

Shrink the consumers of direct memory

• Managed ledger cache. managedLedgerCacheSizeMB in broker.conf. Recent Pulsar versions default this to a fraction of direct memory (20% in current code; older docs describe different ratios, so check your version). If the cache plus everything else exceeds the direct budget, the cache loses.
• Publish buffer limiter. maxMessagePublishBufferSizeInMB bounds memory held for unacknowledged publishes. Disabling it (-1) has caused direct memory OOM under load; keep it enabled and sized.
• Dispatcher read batch. Large dispatcher read sizes combined with big messages mean single read batches allocate large direct buffers. If EntryFilters or catch-up reads are in play, review dispatcherMaxReadSizeBytes (default 5 MB in current versions) and batch settings; the right value is workload- and version-dependent.

Fix the driver, not just the budget

If the growth pattern said leak or storm, raising the limit only postpones the crash. Fix client connection handling, close per-topic connection configurations, and check whether you are on a Pulsar version with known Netty buffer leaks or missing channel backpressure. PIP-434 (landed in the 4.1.x and 4.0.x lines: 4.1.2 and 4.0.8) exposes Netty channel write buffer watermarks (pulsarChannelWriteBufferHighWaterMark, default 64 KB) and pauses receive requests when a slow consumer’s channel is unwritable, addressing a real path by which slow consumers accumulate broker-side direct buffers. If slow-consumer backpressure is your failure mode, upgrading matters more than resizing.

Also review the deliberate-death knobs: -Dpulsar.allocator.exit_on_oom and skipBrokerShutdownOnOOM. With the shipped defaults (exit_on_oom=false, skipBrokerShutdownOnOOM=false) the allocator falls back to heap but the broker’s OOM listener still shuts the broker down; there is no single maintainer-recommended production setting, so understand the blast radius either way before changing them.

Prevention

• Monitor direct memory as a first-class signal. Scrape java.nio:type=BufferPool,name=direct via a JMX exporter on every broker and bookie. Alert at 75% of MaxDirectMemorySize sustained; the failure is a cliff, so the alert must fire before the edge.
• Track RSS minus heap as a backup proxy in case the JMX pipeline dies.
• Trend connection counts over weeks, not minutes. The classic leak is invisible on a 6-hour dashboard.
• Budget memory explicitly per host: heap + MaxDirectMemorySize + roughly 20% JVM overhead, under the container limit. Bookie defaults of 2g heap and 2g direct are easy to outgrow; revisit them for loaded clusters.
• Load-test connection storms (mass reconnect after broker restart) before they happen in production, and record what direct memory does. That is your real headroom number.
• Keep current. Direct-memory leak fixes and backpressure improvements ship regularly; a broker two years behind is carrying known crash modes.

How Netdata helps

• Netdata’s JVM/JMX collection can track the direct buffer pool (java.nio:type=BufferPool,name=direct) alongside heap, closing the exact visibility gap that makes this failure a surprise.
• Per-second process memory metrics (RSS, page faults) make the RSS-versus-heap divergence visible as a trend, not a postmortem discovery.
• Scraping the broker’s Prometheus endpoint puts pulsar_active_connections, connection created/closed churn, and pulsar_ml_cache_* on the same timeline as host memory, so the correlation step in diagnosis is a single view.
• Connection churn, throughput, and cache eviction anomalies surface early via ML-based anomaly detection, which matters because direct memory exhaustion gives no gradual warning of its own.
• Host-level cgroup and container memory tracking catches the case where heap plus direct memory plus overhead approaches the container limit before the kernel OOM killer does.

Related guides

• Apache Pulsar broker down: telling a dead broker from a fenced one
• Apache Pulsar monitoring checklist: the signals every production cluster needs