apache/cassandra · error · ConfigurationException

Invalid configuration. Heap dump is enabled but cannot creat

Error message

Invalid configuration. Heap dump is enabled but cannot create heap dump output path: %s.

What it means

When dump_heap_on_uncaught_exception is enabled, Cassandra must be able to resolve a writable heap dump output path. DatabaseDescriptor throws this ConfigurationException when the heap dump path is unset (getHeapDumpPath() returns null) or cannot be created, so an OOM crash could not produce the requested dump.

Source

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

        {
            throw new ConfigurationException(String.format("default_keyspace_rf (%d) cannot be less than minimum_replication_factor_fail_threshold (%d)",
                                                           conf.default_keyspace_rf, conf.minimum_replication_factor_fail_threshold));
        }

        if (conf.paxos_repair_parallelism <= 0)
            conf.paxos_repair_parallelism = Math.max(1, conf.concurrent_writes / 8);

        Paxos.setPaxosVariant(conf.paxos_variant);
        if (conf.paxos_state_purging == null)
            conf.paxos_state_purging = PaxosStatePurging.legacy;

        logInitializationOutcome(logger);

        if (conf.max_space_usable_for_compactions_in_percentage < 0 || conf.max_space_usable_for_compactions_in_percentage > 1)
            throw new ConfigurationException("max_space_usable_for_compactions_in_percentage must be between 0 and 1", false);

        if (conf.dump_heap_on_uncaught_exception && DatabaseDescriptor.getHeapDumpPath() == null)
            throw new ConfigurationException(String.format("Invalid configuration. Heap dump is enabled but cannot create heap dump output path: %s.", conf.heap_dump_path != null ? conf.heap_dump_path : "null"));

        conf.sai_options.validate();

        List<ConsistencyLevel> progressBarrierCLsArr = Arrays.asList(ALL, EACH_QUORUM, LOCAL_QUORUM, QUORUM, ONE, NODE_LOCAL);
        Set<ConsistencyLevel> progressBarrierCls = new HashSet<>(progressBarrierCLsArr);
        if (!progressBarrierCls.contains(conf.progress_barrier_min_consistency_level))
        {
            throw new ConfigurationException(String.format("Invalid value for progress_barrier_min_consistency_level %s. Allowed values: %s",
                                                           conf.progress_barrier_min_consistency_level, progressBarrierCLsArr));
        }

        if (!progressBarrierCls.contains(conf.progress_barrier_default_consistency_level))
        {
            throw new ConfigurationException(String.format("Invalid value for.progress_barrier_default_consistency_level %s. Allowed values: %s",
                                                           conf.progress_barrier_default_consistency_level, progressBarrierCLsArr));
        }

        if (conf.native_transport_min_backoff_on_queue_overload.toMilliseconds() <= 0)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set heap_dump_path in cassandra.yaml to a writable directory/file path
2. Ensure the Cassandra process user has write permission to the directory and enough disk space
3. Disable dump_heap_on_uncaught_exception if heap dumps are not needed

Example fix

// before (cassandra.yaml)
dump_heap_on_uncaught_exception: true
# heap_dump_path not set
// after
dump_heap_on_uncaught_exception: true
heap_dump_path: /var/lib/cassandra/heapdump.hprof

if (conf.dump_heap_on_uncaught_exception) { java.nio.file.Path p = java.nio.file.Paths.get(conf.heap_dump_path != null ? conf.heap_dump_path : "./heapdump.hprof"); java.nio.file.Files.createDirectories(p.toAbsolutePath().getParent()); if (!java.nio.file.Files.isWritable(p.toAbsolutePath().getParent())) throw new IllegalStateException("heap dump path not writable"); }

try { DatabaseDescriptor.toolInitialization(); } catch (ConfigurationException e) { log.error("Heap dump path invalid: {}", e.getMessage()); }

When it happens

Trigger: applySimpleConfig (via toolInitialization/applyAll) with dump_heap_on_uncaught_exception=true and heap_dump_path unset or pointing to an uncreatable location.

Common situations: Enabling heap dumps in a container without a writable volume for the dump path; forgetting to set heap_dump_path; path pointing to a read-only mount.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Neither -XX:HeapDumpPath nor cassandra.yaml:heap_dump_path a
• Load CIDR groups cache operation not supported by %s
• Unsupported parameter '%s' for %s, supported parameters are
• JAAS login configuration missing for JMX authenticator setup
• repair_session_max_tree_depth should not be < 10, but was ${

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