Skip to content

AxonOps — AI-Native Control Plane for Open Source Data Platforms

JVM Tuning for Cassandra

The heap size and the garbage collector are chosen by the packaged Cassandra configuration rather than left to the JVM defaults. This page covers what each release sets on Cassandra 5.0, 4.1 and 4.0: the heap, direct memory, GC logging and the procedure for changing any of them. The settings of each collector, and which of them are worth changing, are on a page per collector, reached from Collector by Version.

JVM Architecture gives the reasoning behind these defaults, and Memory Management introduces the memory pools a node divides its memory into.

The heap formula changed inside 5.0, at 5.0.4 (CASSANDRA-20296), so every heap claim below names a patch range rather than 5.0 as a whole.


conf/cassandra-env.sh computes the heap at start and appends -Xms and -Xmx to the command line. The heap is in no options file, so searching jvm-server.options or jvm11-server.options for -Xmx on a default install finds nothing. Read the effective values from the running process instead:

Terminal window
ps -o args= -p "$(pgrep -fn CassandraDaemon)" | tr ' ' '\n' \
| grep -E '^-Xm|MaxDirectMemorySize|UseG1GC|UseConcMarkSweepGC|Xlog:gc'
Setting5.0.4 and later5.0.0 to 5.0.34.1 and 4.0
Max heap, when -Xmx is unset in jvm-server.optionsmin(1/2 RAM, 31744M) under G1max(min(1/2 RAM, 1024M), min(1/4 RAM, 8192M))max(min(1/2 RAM, 1024M), min(1/4 RAM, 8192M))
Collector active on a default installThe Garbage-First collector (G1), in jvm11-server.options and jvm17-server.optionsG1, in both filesThe Concurrent Mark Sweep collector (CMS), in jvm11-server.options, with a full G1 block commented out in the same file
-XX:MaxDirectMemorySizehalf the max heapnot set, so the JVM defaults it to the max heapnot set, so the JVM defaults it to the max heap
-XX:ParallelGCThreads, -XX:ConcGCThreadsboth set to the core count when neither is set in the options filesnot set, so the JVM defaults applynot set, so the JVM defaults apply
GC logging-Xlog:gc to $CASSANDRA_LOG_DIR/gc.log, 10 files of 10MiBsamesame
On OutOfMemoryErrorheap dump written, then kill -9 of the processsamesame
Thread stack size-Xss256k, active in jvm-server.optionssamesame
Heap page pre-touch-XX:+AlwaysPreTouch, active in jvm-server.optionssamesame

The out-of-memory action comes from cassandra-env.sh rather than from an options file. The same script carries -XX:+ExitOnOutOfMemoryError and -XX:+CrashOnOutOfMemoryError commented out immediately above it as alternatives to swap in; neither is active on 5.0, 4.1 or 4.0, and neither needs adding to obtain the shipped behaviour. The packages install an LSB SysV init script and no systemd unit, so nothing restarts the process after the kill.

The 5.0.4 row changes are CASSANDRA-20296. G1 became the collector active on a default install in 5.0.0 (CASSANDRA-18027). The older heap formula dates to CASSANDRA-3295.

The min(1/2 RAM, 15872M) branch of the 5.0.4 formula applies only where CMS has been enabled by hand, since G1 is the collector active in both per-JDK options files on 5.0.

-XX:-UseBiasedLocking is a general setting rather than part of a collector block. It is active on every 5.0 patch version, in the general settings section of jvm11-server.options, and on 4.1 and 4.0 in jvm-server.options, where it applies under every JDK those releases support. Biased locking lets a lock repeatedly taken by one thread skip the atomic operation on each acquisition, and revoking the bias when another thread takes the lock costs a safepoint; the shipped comment records that the optimisation does not benefit Cassandra. jvm17-server.options does not set it, because JDK 15 disabled biased locking by default (JEP 374).

Cassandra reads one per-JDK options file in addition to jvm-server.options, chosen by the JDK the daemon starts under, and the collector flags live in that file. 5.0 supports JDK 11 and JDK 17 and ships jvm-server.options, jvm11-server.options and jvm17-server.options. 4.1 and 4.0 support JDK 11 and ship jvm-server.options, jvm8-server.options and jvm11-server.options; neither ships a jvm17-server.options, so JDK 17 has no per-JDK file to read on them.

Running 5.0 under JDK 17 needs no module flags added by hand. jvm17-server.options carries the full set of --add-opens and --add-exports entries the process requires, among them --add-opens java.base/java.io=ALL-UNNAMED and --add-opens java.base/sun.nio.ch=ALL-UNNAMED. None of them are set in cassandra-env.sh. Adding any of these flags to another options file repeats what the release already ships and changes nothing.


On 5.0.4 and later the heap is half of host memory, capped at 31744M under G1. On 5.0.0 to 5.0.3, 4.1 and 4.0 it is the larger of half of host memory capped at 1024M and a quarter of host memory capped at 8192M, so the cap that binds on any host with more than 32GB is 8192M.

The memory figure comes from free -m on Linux, which reports slightly less than the nominal size of the host, so the computed heap is close to the values below rather than exactly equal to them.

Host RAM5.0.4 and later5.0.0 to 5.0.3, 4.1 and 4.0
8GB4G2G
16GB8G4G
32GB16G8G
64GB31744M8G
128GB31744M8G

On 5.0.4 and later, -XX:MaxDirectMemorySize is half of the computed heap: 2G on an 8GB host, 4G on a 16GB host, 8G on a 32GB host, and 15872M wherever the heap cap binds.

The two formulas diverge with host size. Up to a 32GB host, 5.0.4 and later give roughly twice the heap that 4.1 gives on the same hardware. From 64GB upward both formulas are capped, at 31744M and 8192M, so the ratio settles at roughly four times and stays there however large the host is. A heap value carried over from a 4.x cluster is therefore not a sound starting point for a node on 5.0.4 or later, and the reverse applies to a value moved from 5.0.4 or later back to 4.1.

The heap changes silently between 5.0.3 and 5.0.4

The formula change in 5.0.4 has no NEWS.txt entry, and the heap is not written in any options file, so an upgrade from 5.0.3 to 5.0.4 gives the node a different heap with no signal in the configuration or the upgrade notes. The new heap is larger at every host size in the table above: roughly twice as large up to a 32GB host, and roughly four times as large from 64GB upward, where both formulas are capped. The extra heap comes out of the page cache and lengthens each collection. Record the max heap before the upgrade with nodetool info | grep "Heap Memory", compare it after the first node restarts, and decide deliberately whether to keep the new value or pin the previous one.

Two mechanisms override the computation. Where both are present, the options file wins, because cassandra-env.sh appends its own -Xms and -Xmx only when the options file sets neither.

  • -Xmx and -Xms in jvm-server.options. Both must be present or both absent; setting one alone stops the start with a message asking for the pair. When both are set, the computation in cassandra-env.sh is skipped entirely and the pinned value applies regardless of host memory.
  • MAX_HEAP_SIZE in the environment, which cassandra-env.sh reads before computing. The rule follows the collector in use rather than the release. Under G1, MAX_HEAP_SIZE may be set on its own, and HEAP_NEWSIZE is ignored with a warning printed at start. Under any other collector, including CMS on 4.1 and 4.0, MAX_HEAP_SIZE and HEAP_NEWSIZE must be set as a pair, and setting one alone stops the node starting with a message asking for both.

Set -Xms equal to -Xmx wherever the heap is pinned. The computed path already does this, and an equal pair avoids heap resizing during operation.

A departure from the shipped formula should follow a measured garbage collection profile rather than a rule based on host memory. The measurement that supports a change is heap occupancy after collection over hours of representative load, together with pause durations from the GC log, not a single peak reading. Raising the heap without changing what allocates moves an allocation failure later rather than removing it, and it lengthens each collection.

Two departures have a defensible basis:

  • Smaller than the formula on off-heap-heavy configurations. Where the chunk cache is enlarged or memtables run with memtable_allocation_type: offheap_objects, the heap competes with off-heap pools and with the operating system page cache for the same host memory. On 5.0.4 and later the direct buffer pool is already sized at half the heap, so each gibibyte of heap claims another half gibibyte of address space for direct buffers.
  • Smaller than host memory suggests when the node runs in a container. cassandra-env.sh reads host memory rather than the cgroup limit, so the computed heap can exceed the memory the process is actually allowed. Recover from OOM covers that case and the kernel kill it produces.

Raising the heap above the shipped cap is covered in JVM Architecture: above the boundary every object reference widens, so a larger heap holds proportionally less data.


What a release starts with and what it supports are separate questions. Each of 5.0, 4.1 and 4.0 starts with one collector active in the per-JDK options file and carries the other in the same file as a commented block. That block is a complete configuration rather than a placeholder, so both collectors are available on all three releases wherever the JDK provides them.

ReleaseActive on a default installAlso in the options files, commented out
5.0 (all patch versions)G1, in jvm11-server.options and jvm17-server.optionsCMS, in jvm11-server.options only
4.1CMS, in jvm11-server.optionsG1, in jvm11-server.options, tuned and commented by the project
4.0CMS, in jvm11-server.optionsG1, in jvm11-server.options, tuned and commented by the project

A node reporting a collector other than the one its release starts with has been configured by hand. Check with the ps command in What the Release Already Sets.

Settings for a collector the node is not running are ignored, so an options file carrying two active collector blocks records a configuration that is not in effect. The settings for the collector already active are in the per-JDK file, so re-adding one changes nothing.

Each collector has a page of its own:

  • G1 is active on a default install of 5.0, in both jvm11-server.options and jvm17-server.options, on every patch version (CASSANDRA-18027); 5.0.4 retuned it rather than changing collector. On 4.1 and 4.0 it is available in the same file as a commented block.
  • CMS is active on a default install of 4.1 and 4.0. JDK 14 removed the collector, so it is unavailable on 5.0 under JDK 17 and is present on 5.0 under JDK 11 only as a commented block.
  • Shenandoah appears in no options file on any of the three releases. AxonOps recommends it over G1 for Cassandra, with the compact heuristic in place of the JDK default, and it is present only in JDK builds compiled with it. AxonOps recommends Azul Zulu Builds of OpenJDK, which carry the collector from OpenJDK 11.0.9.
  • ZGC appears in no options file on any of the three releases and is not recommended by the project, which records it as experimental in Java 11 and not fully supported before JDK 15.

Choosing Between CMS and G1 on 4.1 and 4.0

Section titled “Choosing Between CMS and G1 on 4.1 and 4.0”

G1 is a documented configuration on 4.1 and 4.0 and a common choice on both. The block in jvm11-server.options carries a pause goal, remembered-set settings and, on 4.1, a region size and tenuring threshold, each with the project's own explanatory comment. Selecting G1 means uncommenting that block and commenting out the CMS block; G1 gives the exact lines for each release. G1 is present in every JDK build those releases support, so no change of JDK is involved.

The following is AxonOps operational guidance rather than a project position, since the project ships CMS active on both releases and states no preference.

  • Prefer G1 over CMS once the heap is above about 8GB. CMS sweeps in place without compacting, so a larger old generation fragments further before a full compacting collection becomes unavoidable, and the duration of that collection scales with the live set rather than with any goal.
  • Prefer G1 where the effort of tuning CMS is not worth spending. CMS has considerably more settings, and they interact: the occupancy trigger, the tenuring threshold and the survivor ratio each change how much data reaches the old generation and how soon a cycle has to start, so a change to one is measured against the others. G1 works to a single pause goal and sizes the young generation itself.
  • Shenandoah is the other alternative on 4.1 and 4.0. It needs a JDK build compiled with the collector, which the Cassandra packages do not provide.

What G1 gives up for that is throughput. Collecting one region without scanning the rest of the heap requires G1 to know which references point into that region, so it keeps a remembered set per region and a write barrier that records cross-region references as the application runs. Maintaining those sets costs CPU during each pause and on the concurrent refinement threads, and the sets themselves occupy heap. CMS collects the whole old generation in one cycle, so it needs no per-region view of incoming references: its write barrier is cheaper, and the card table it does keep is far smaller than G1's remembered sets.

That cost is what fixes the guidance at roughly 8GB of heap. Below it the old generation is small enough that a CMS cycle completes quickly and fragments little before a compacting collection is forced, so G1's bookkeeping is paid without much pause duration to recover in return. Above it the full compacting collection CMS falls back to grows with the live set, and the bookkeeping buys a bounded pause instead.

Changing collector on 4.1 or 4.0 does not change the heap. cassandra-env.sh on those releases computes the same max heap whatever the collector, capped at 8192M, so the 8GB threshold above is reached only where -Xmx or MAX_HEAP_SIZE has been pinned above the computed value.


On 5.0.4 and later, cassandra-env.sh sets -XX:MaxDirectMemorySize to half the max heap, which puts a known bound on the pool that holds network and compression buffers. MAX_DIRECT_MEMORY_SIZE in the environment, or -XX:MaxDirectMemorySize in jvm-server.options, overrides it.

Off-heap-heavy configurations can exhaust that bound. A 5.0.6 cluster has been reported failing with OutOfMemoryError: Direct buffer memory against the half-heap default (CASSANDRA-21529). Where the chunk cache is enlarged or memtables run with memtable_allocation_type: offheap_objects, size the setting against the measured pool rather than leaving the default in place, and account for the raised value in total process memory.

The flag is set from 5.0.4 onward, and not on 5.0.0 to 5.0.3, 4.1 and 4.0, where the JVM then defaults the limit to the max heap. Direct buffers can therefore add close to a second heap of resident memory on those earlier releases, which is the usual explanation for a container being killed by the kernel while the JVM reports a healthy heap. Setting the flag explicitly there gives the pool a known bound.

The distinction between heap, direct memory and the rest of process memory is covered in JVM Architecture.


GC logging is already enabled. On 5.0, 4.1 and 4.0, cassandra-env.sh appends an -Xlog:gc configuration writing to $CASSANDRA_LOG_DIR/gc.log, rotating 10 files of 10MiB, unless the options files already mention -Xlog:gc. The log directory is /var/log/cassandra in the packaged layout.

Mentioning -Xlog:gc in an options file replaces the shipped configuration rather than adding to it, so a custom line must carry its own file, rotation and decorator settings:

Terminal window
# jvm11-server.options or jvm17-server.options
# Replaces the configuration cassandra-env.sh would otherwise append
-Xlog:gc*,safepoint:file=/var/log/cassandra/gc.log:time,uptime,pid,level:filecount=10,filesize=10485760

Keep the file count and size bounded on a filesystem shared with system.log, and confirm the file is being written after the restart.


-XX:+UseLargePages directs the JVM to back the heap with HugeTLB pages, which are explicitly reserved large pages (2MB on x86-64). This is not the same feature as Transparent Huge Pages (THP): HugeTLB pages are statically reserved by the operator, whereas THP is managed automatically by the kernel. THP should remain disabled (see Linux Memory Configuration) whether or not HugeTLB large pages are used for the heap.

The flag has no effect unless huge pages are reserved on the host first. With none reserved, the JVM falls back to 4KB pages without failing, so the option silently does nothing. Reserve enough huge pages to cover the heap (-XX:+AlwaysPreTouch ships active on 5.0, 4.1 and 4.0 and touches the whole heap at start, so the full reservation is used):

Terminal window
# Reserve slightly more than a 16GB heap: 16GB / 2MB = 8192 pages, plus headroom
sudo sysctl vm.nr_hugepages=8400
echo "vm.nr_hugepages = 8400" | sudo tee -a /etc/sysctl.conf
Terminal window
# jvm-server.options
-XX:+UseLargePages

Verify the heap is actually backed by large pages at startup. -Xlog:gc+init reports the page size the heap uses; if the reservation was insufficient the JVM logs the fallback rather than the large-page size:

Terminal window
# Add -Xlog:gc+init to the options, restart, then inspect the log
grep -iE "large page|page size|hugepage" /var/log/cassandra/gc.log

Every setting on this page takes effect at the next start of the node, and none can be changed on a running JVM. Apply changes node by node, letting each node return to UN in nodetool status before restarting the next.

Record the same measurements before and after, over a period of representative load rather than at a single moment:

Terminal window
# Max heap and used heap as the JVM reports them
nodetool info | grep "Heap Memory"
# Collection counts and times since the last call
nodetool gcstats
# Resident memory of the process, which includes direct buffers and native allocations
ps -o rss= -p "$(pgrep -fn CassandraDaemon)"

A change is an improvement when pause durations fall, or heap occupancy after collection falls, without read and write latency worsening. A collector or heuristic change that improves pauses while raising CPU use enough to raise request latency is not an improvement for that workload.

Roll a change back by restoring the previous options file and restarting the node, which is why the previous values should be kept rather than overwritten in place.


  • JVM Architecture - The pointer-compression boundary, where the heap sits in process memory, and why the heap formula changed
  • G1 - Active on 5.0, available on 4.1 and 4.0, and what changing each setting costs
  • CMS - Active on 4.1 and 4.0, and its fixed occupancy trigger
  • Shenandoah - Heuristics, region size and collection threads for a node running Shenandoah
  • ZGC - The project position on the collector and the JDK constraints that apply
  • JVM Options - The options files, what the installation already provides, and the settings worth reviewing on a new cluster
  • Cassandra Memory Structures - Cassandra on-heap and off-heap structures
  • Linux Memory Configuration - Page cache, swap and THP on the host
  • Recover from OOM - Diagnosis after a node is lost to memory exhaustion
  • GC Pause Issues - Long pauses without an allocation failure
  • OS Tuning - Host settings outside the JVM
  • Hardware - Memory sizing for the host