Configuring the heap dump directory

Analyzing the heap dump file can help troubleshoot memory problems.

Analyzing the heap dump file can help troubleshoot memory problems. Cassandra starts Java with the option -XX:+HeapDumpOnOutOfMemoryError. Using this option triggers a heap dump in the event of an out-of-memory condition. The heap dump file consists of references to objects that cause the heap to overflow. By default, Cassandra puts the file a subdirectory of the working, root directory when running as a service. If Cassandra does not have write permission to the root directory, the heap dump fails. If the root directory is too small to accommodate the heap dump, the server crashes.

To ensure that a heap dump succeeds and to prevent crashes, configure a heap dump directory that is:

  • Accessible to Cassandra for writing
  • Large enough to accommodate a heap dump
The location of the file depends on the type of installation:
DataStax Enterprise 5.0 Installer-Services and package installations /etc/dse/cassandra/
DataStax Enterprise 5.0 Installer-No Services and tarball installations install_location/resources/cassandra/conf/
Cassandra package installations /etc/cassandra/
Cassandra tarball installations install_location/conf/

Base the size of the directory on the value of the Java -mx option.


Set the location of the heap dump in the file.

  1. Open the file for editing.
  2. Scroll down to the comment about the heap dump path:
    # set jvm HeapDumpPath with CASSANDRA_HEAPDUMP_DIR
    if [ "x$CASSANDRA_HEAPDUMP_DIR" != "x" ]; then
    JVM_OPTS="$JVM_OPTS -XX:HeapDumpPath=$CASSANDRA_HEAPDUMP_DIR/cassandra-`date +%s`-pid$$.hprof"
  3. On the line after the comment, set the CASSANDRA_HEAPDUMP_DIR to the path you want to use:
    # set jvm HeapDumpPath with CASSANDRA_HEAPDUMP_DIR 
    if [ "x$CASSANDRA_HEAPDUMP_DIR" != "x" ]; then
    JVM_OPTS="$JVM_OPTS -XX:HeapDumpPath=$CASSANDRA_HEAPDUMP_DIR/cassandra-`date +%s`-pid$$.hprof"
  4. Save the file and restart.