{"record":{"id":"1dceabb9141e3970","repo":"apache/cassandra","slug":"cannot-create-heap-dump-unless-xx-heapdumppath-or","errorCode":null,"errorMessage":"Cannot create heap dump unless -XX:HeapDumpPath or cassandra.yaml:heap_dump_path is specified.","messagePattern":"Cannot create heap dump unless -XX:HeapDumpPath or cassandra\\.yaml:heap_dump_path is specified\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/utils/HeapUtils.java","lineNumber":110,"sourceCode":"    public static String maybeCreateHeapDump()\n    {\n        // Make sure that only one heap dump can be in progress across all threads, and abort for\n        // threads that cannot immediately acquire the lock, allowing them to fail normally.\n        if (DUMP_LOCK.tryLock())\n        {\n            try\n            {\n                if (DatabaseDescriptor.getDumpHeapOnUncaughtException())\n                {\n                    MBeanServer server = ManagementFactory.getPlatformMBeanServer();\n\n                    Path absoluteBasePath = DatabaseDescriptor.getHeapDumpPath();\n                    // We should never reach this point with this value null as we initialize the bool only after confirming\n                    // the -XX param / .yaml conf is present on initial init and the JMX entry point, but still worth checking.\n                    if (absoluteBasePath == null)\n                    {\n                        DatabaseDescriptor.setDumpHeapOnUncaughtException(false);\n                        throw new RuntimeException(\"Cannot create heap dump unless -XX:HeapDumpPath or cassandra.yaml:heap_dump_path is specified.\");\n                    }\n\n                    long maxMemoryBytes = Runtime.getRuntime().maxMemory();\n                    long freeSpaceBytes = PathUtils.tryGetSpace(absoluteBasePath, FileStore::getUnallocatedSpace);\n\n                    // Abort if there isn't enough room on the target disk to dump the entire heap and then copy it.\n                    if (freeSpaceBytes < 2 * maxMemoryBytes)\n                        throw new RuntimeException(\"Cannot allocated space for a heap dump snapshot. There are only \" + freeSpaceBytes + \" bytes free at \" + absoluteBasePath + '.');\n\n                    HotSpotDiagnosticMXBean mxBean = ManagementFactory.newPlatformMXBeanProxy(server, \"com.sun.management:type=HotSpotDiagnostic\", HotSpotDiagnosticMXBean.class);\n                    String filename = String.format(\"pid%s-epoch%s.hprof\", HeapUtils.getProcessId().toString(), currentTimeMillis());\n                    String fullPath = File.getPath(absoluteBasePath.toString(), filename).toString();\n\n                    logger.info(\"Writing heap dump to {} on partition w/ {} free bytes...\", absoluteBasePath, freeSpaceBytes);\n                    mxBean.dumpHeap(fullPath, false);\n                    logger.info(\"Heap dump written to {}\", fullPath);\n\n                    // Disable further heap dump creations until explicitly re-enabled.","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/utils/HeapUtils.java#L92-L128","documentation":"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.","triggerScenarios":"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.","commonSituations":"Operators turn on heap dumping during debugging but forget to set the dump path, or the JVM was started with HeapDumpOnOutOfMemoryError only, without HeapDumpPath.","solutions":["Add -XX:HeapDumpPath=/var/lib/cassandra/heapdump to the JVM options (jvm-server.options)","Or set heap_dump_path: /var/lib/cassandra/heapdump in cassandra.yaml","Ensure the directory exists and is writable by the Cassandra user","Disable dump_heap_on_uncaught_exception if heap dumps are not wanted"],"exampleFix":"// before (jvm-server.options): # no HeapDumpPath set\n// after (jvm-server.options): -XX:HeapDumpPath=/var/lib/cassandra/heapdump/","handlingStrategy":"validation","validationCode":"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\");","typeGuard":null,"tryCatchPattern":"try { HeapUtils.maybeCreateHeapDump(); } catch (RuntimeException e) { logger.error(\"Heap dump skipped: {}\", e.getMessage()); }","preventionTips":["Set -XX:HeapDumpPath whenever enabling dump_heap_on_uncaught_exception","Verify the dump directory exists and is writable at startup","Prefer cassandra.yaml heap_dump_path for consistency across nodes"],"tags":["heap-dump","configuration","diagnostics"],"backgroundTag":"missing-required-config-field","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}