Neither -XX:HeapDumpPath nor cassandra.yaml:heap_dump_path a

Error message

Neither -XX:HeapDumpPath nor cassandra.yaml:heap_dump_path are set; unable to create a directory to hold the output.

What it means

When dump_heap_on_uncaught_exception is enabled, Cassandra checks before startup (or on fatal error) that a heap dump directory exists or can be created. If neither the -XX:HeapDumpPath JVM flag nor cassandra.yaml heap_dump_path is set, getHeapDumpPath() returns null and this warning is logged, disabling the heap dump feature. No exception is thrown.

Source

Thrown at src/java/org/apache/cassandra/config/DatabaseDescriptor.java:6067

    }

    public static boolean getDumpHeapOnUncaughtException()
    {
        return conf.dump_heap_on_uncaught_exception;
    }

    /**
     * @return Whether the path exists (be it created now or already prior)
     */
    private static boolean maybeCreateHeapDumpPath()
    {
        if (!conf.dump_heap_on_uncaught_exception)
            return false;

        Path heap_dump_path = getHeapDumpPath();
        if (heap_dump_path == null)
        {
            logger.warn("Neither -XX:HeapDumpPath nor cassandra.yaml:heap_dump_path are set; unable to create a directory to hold the output.");
            return false;
        }
        if (PathUtils.exists(File.getPath(conf.heap_dump_path)))
            return true;
        return PathUtils.createDirectoryIfNotExists(File.getPath(conf.heap_dump_path));
    }

    /**
     * As this is at its heart a debug operation (getting a one-shot heapdump from an uncaught exception), we support
     * both the more evolved cassandra.yaml approach but also the -XX param to override it on a one-off basis so you don't
     * have to change the full config of a node or a cluster in order to get a heap dump from a single node that's
     * misbehaving.
     *
     * @return the absolute path of the -XX param if provided, else the heap_dump_path in cassandra.yaml
     */
    public static Path getHeapDumpPath()
    {
        RuntimeMXBean runtimeMxBean = ManagementFactory.getRuntimeMXBean();

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Add heap_dump_path: /var/lib/cassandra/heapdump (or similar) to cassandra.yaml, or add -XX:HeapDumpPath=/path to jvm-server.options
Pre-create the directory with write permission for the cassandra user
If heap dumps are not wanted, set dump_heap_on_uncaught_exception: false

Example fix

// cassandra.yaml before
dump_heap_on_uncaught_exception: true
// after
dump_heap_on_uncaught_exception: true
heap_dump_path: /var/lib/cassandra/heapdump

Defensive patterns

Strategy: validation

Validate before calling

if (cfg.dumpHeapOnUncaughtException && (cfg.heapDumpPath == null || cfg.heapDumpPath.isEmpty())
    && System.getenv("JVM_EXTRA_OPTS") != null && !System.getenv("JVM_EXTRA_OPTS").contains("HeapDumpPath"))
    throw new IllegalStateException("dump_heap_on_uncaught_exception requires heap_dump_path or -XX:HeapDumpPath");

Prevention

Always set -XX:HeapDumpPath in jvm-server.options when enabling heap dumps
Pre-create and chown the dump directory
Test heap dump creation in staging (jmap trigger)

When it happens

Trigger: cassandra.yaml has dump_heap_on_uncaught_exception: true but heap_dump_path is unset and the JVM is started without -XX:HeapDumpPath; checked in DatabaseDescriptor.createHeapDumpPathIfNotExists().

Common situations: Operators enabling automatic heap dump on OOM/uncaught exceptions but forgetting to configure where dumps go; containers where the default path is not writable.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/40490f1dbe87f40e. Report an issue: GitHub.