apache/cassandra · error · RuntimeException

Cannot create heap dump unless -XX:HeapDumpPath or…

Error message

Cannot create heap dump unless -XX:HeapDumpPath or cassandra.yaml:heap_dump_path is specified.

What it means

HeapUtils.maybeCreateHeapDump, invoked on uncaught exceptions when dump_heap_on_uncaught_exception is enabled, writes an hprof heap dump to the configured heap dump path. This RuntimeException is thrown when no heap dump location was configured via -XX:HeapDumpPath or cassandra.yaml heap_dump_path, so dumping cannot proceed; the flag is also disabled.

Solutions

  1. Add -XX:HeapDumpPath=/var/lib/cassandra/heapdump to the JVM options (jvm-server.options)
  2. Or set heap_dump_path: /var/lib/cassandra/heapdump in cassandra.yaml
  3. Ensure the directory exists and is writable by the Cassandra user
  4. Disable dump_heap_on_uncaught_exception if heap dumps are not wanted

Example fix

// before (jvm-server.options): # no HeapDumpPath set
// after (jvm-server.options): -XX:HeapDumpPath=/var/lib/cassandra/heapdump/
Defensive patterns

Strategy: validation

Validate before calling

boolean ok = jvmOpts.contains("HeapDumpPath") || cassandraYaml.containsKey("heap_dump_path"); if (!ok && dumpHeapOnUncaught) throw new ConfigurationException("dump_heap_on_uncaught_exception requires a heap_dump_path");

Try / catch

try { HeapUtils.maybeCreateHeapDump(); } catch (RuntimeException e) { logger.error("Heap dump skipped: {}", e.getMessage()); }

Prevention

When it happens

Trigger: Enabling dump_heap_on_uncaught_exception: true in cassandra.yaml (or via the JMX entry point) without setting -XX:HeapDumpPath=/path or heap_dump_path: /path in cassandra.yaml, then an uncaught exception triggers heap dump creation.

Common situations: Operators turn on heap dumping during debugging but forget to set the dump path, or the JVM was started with HeapDumpOnOutOfMemoryError only, without HeapDumpPath.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/utils/HeapUtils.java:110

    public static String maybeCreateHeapDump()
    {
        // Make sure that only one heap dump can be in progress across all threads, and abort for
        // threads that cannot immediately acquire the lock, allowing them to fail normally.
        if (DUMP_LOCK.tryLock())
        {
            try
            {
                if (DatabaseDescriptor.getDumpHeapOnUncaughtException())
                {
                    MBeanServer server = ManagementFactory.getPlatformMBeanServer();

                    Path absoluteBasePath = DatabaseDescriptor.getHeapDumpPath();
                    // We should never reach this point with this value null as we initialize the bool only after confirming
                    // the -XX param / .yaml conf is present on initial init and the JMX entry point, but still worth checking.
                    if (absoluteBasePath == null)
                    {
                        DatabaseDescriptor.setDumpHeapOnUncaughtException(false);
                        throw new RuntimeException("Cannot create heap dump unless -XX:HeapDumpPath or cassandra.yaml:heap_dump_path is specified.");
                    }

                    long maxMemoryBytes = Runtime.getRuntime().maxMemory();
                    long freeSpaceBytes = PathUtils.tryGetSpace(absoluteBasePath, FileStore::getUnallocatedSpace);

                    // Abort if there isn't enough room on the target disk to dump the entire heap and then copy it.
                    if (freeSpaceBytes < 2 * maxMemoryBytes)
                        throw new RuntimeException("Cannot allocated space for a heap dump snapshot. There are only " + freeSpaceBytes + " bytes free at " + absoluteBasePath + '.');

                    HotSpotDiagnosticMXBean mxBean = ManagementFactory.newPlatformMXBeanProxy(server, "com.sun.management:type=HotSpotDiagnostic", HotSpotDiagnosticMXBean.class);
                    String filename = String.format("pid%s-epoch%s.hprof", HeapUtils.getProcessId().toString(), currentTimeMillis());
                    String fullPath = File.getPath(absoluteBasePath.toString(), filename).toString();

                    logger.info("Writing heap dump to {} on partition w/ {} free bytes...", absoluteBasePath, freeSpaceBytes);
                    mxBean.dumpHeap(fullPath, false);
                    logger.info("Heap dump written to {}", fullPath);

                    // Disable further heap dump creations until explicitly re-enabled.

View on GitHub (pinned to 88fd0f6a0e)