apache/cassandra · error · org.apache.cassandra.exceptions.ConfigurationException

Attempted to get heap dump path without -XX:HeapDumpPath or

Error message

Attempted to get heap dump path without -XX:HeapDumpPath or cassandra.yaml:heap_dump_path set.

What it means

The heap dump path resolution first checks the JVM's -XX:HeapDumpPath flag; if absent, it falls back to cassandra.yaml's heap_dump_path. When neither is configured, the getter throws ConfigurationException because it cannot determine where to write heap dumps for dump_heap_on_uncaught_exception.

Source

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

     * 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();
        Optional<String> pathArg = runtimeMxBean.getInputArguments().stream().filter(s -> s.startsWith("-XX:HeapDumpPath=")).findFirst();

        if (pathArg.isPresent())
        {
            Pattern HEAP_DUMP_PATH_SPLITTER = Pattern.compile("HeapDumpPath=");
            String fullHeapPathString = HEAP_DUMP_PATH_SPLITTER.split(pathArg.get())[1];
            Path absolutePath = File.getPath(fullHeapPathString).toAbsolutePath();
            Path basePath = fullHeapPathString.endsWith(".hprof") ? absolutePath.subpath(0, absolutePath.getNameCount() - 1) : absolutePath;
            return File.getPath("/").resolve(basePath);
        }
        if (conf.heap_dump_path == null)
            throw new ConfigurationException("Attempted to get heap dump path without -XX:HeapDumpPath or cassandra.yaml:heap_dump_path set.");
        return File.getPath(conf.heap_dump_path);
    }

    public static void setDumpHeapOnUncaughtException(boolean enabled)
    {
        conf.dump_heap_on_uncaught_exception = enabled;
        boolean pathExists = maybeCreateHeapDumpPath();

        if (enabled && !pathExists)
        {
            logger.error("Attempted to enable heap dump but cannot create the requested path. Disabling.");
            conf.dump_heap_on_uncaught_exception = false;
        }
        else
            logger.info("Setting dump_heap_on_uncaught_exception to {}", enabled);
    }

    public static boolean getSStableReadRatePersistenceEnabled()

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set heap_dump_path in cassandra.yaml to a writable directory.
2. Or add -XX:HeapDumpPath=/path/to/dir to jvm.options / JAVA_OPTS.
3. Or disable dump_heap_on_uncaught_exception if heap dumps are not needed.
4. Ensure the configured path exists and the cassandra user can write to it.

Example fix

// before (cassandra.yaml)
# heap_dump_path:
// after (cassandra.yaml)
heap_dump_path: /var/lib/cassandra/heapdumps/

boolean heapDumpConfigured = System.getProperty("jvm.options") != null /* or check jvm args for -XX:HeapDumpPath */ || cassandraYaml.hasPath("heap_dump_path");

null

try { Path p = DatabaseDescriptor.getHeapDumpPath(); } catch (ConfigurationException e) { log.error("heap_dump_path not configured", e); }

When it happens

Trigger: Enabling dump_heap_on_uncaught_exception (via DatabaseDescriptor.setDumpHeapOnUncaughtException(true) or cassandra.yaml) and then triggering heap dump path lookup without setting -XX:HeapDumpPath in jvm.options or heap_dump_path in cassandra.yaml.

Common situations: Operators enable heap dump on OOM/uncaught exception but forget to configure a dump directory; containers where the JVM flag was stripped; configs migrated from versions without heap_dump_path support.

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

• Neither -XX:HeapDumpPath nor cassandra.yaml:heap_dump_path a
• Invalid configuration. Heap dump is enabled but cannot creat
• Threshold value for gc_log*_threshold must be greater than 0
• Threshold value for gc_warn*_threshold must be greater than
• Threshold value for gc_log*_threshold (%d) must be less than

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