apache/cassandra · error · ConfigurationException

commitlog_disk_access_mode =

Error message

commitlog_disk_access_mode =

What it means

When the commit log uses compression or encryption, validateCommitLogWriteDiskAccessMode requires commitlog_disk_access_mode to be standard (or auto); mmap/direct bypass the buffered path those features rely on. The thrown message names the configured mode and whether compression or encryption (or both) conflicts with it.

Source

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

    private static void validateCommitLogWriteDiskAccessMode(Pair<DiskAccessMode, Boolean> accessModeDirectIoPair) throws ConfigurationException
    {
        boolean compressOrEncrypt = getCommitLogCompression() != null || (getEncryptionContext() != null && getEncryptionContext().isEnabled());

        if (!accessModeDirectIoPair.right && accessModeDirectIoPair.left == DiskAccessMode.direct)
        {
            throw new ConfigurationException("commitlog_disk_access_mode can not be set to direct when direct IO is not supported by the file system.");
        }
        else if (compressOrEncrypt && accessModeDirectIoPair.left != DiskAccessMode.standard)
        {
            String with;
            if (null != getCommitLogCompression() && (null != getEncryptionContext() && getEncryptionContext().isEnabled()))
                with = "compression or encryption";
            else if (null != getCommitLogCompression())
                with = "compression";
            else
                with = "encryption";
            throw new ConfigurationException("commitlog_disk_access_mode = " + accessModeDirectIoPair.left + " is not supported with " + with + ". Please use 'auto' when unsure.", false);
        }
        else if (!compressOrEncrypt && accessModeDirectIoPair.left != DiskAccessMode.mmap && accessModeDirectIoPair.left != DiskAccessMode.direct)
        {
            throw new ConfigurationException("commitlog_disk_access_mode = " + accessModeDirectIoPair.left + " is not supported. Please use 'auto' when unsure.", false);
        }
    }

    private static void validateSSTableFormatFactories(Iterable<SSTableFormat.Factory> factories)
    {
        Map<String, SSTableFormat.Factory> factoryByName = new HashMap<>();
        for (SSTableFormat.Factory factory : factories)
        {
            if (factory.name() == null)
                throw new ConfigurationException(String.format("SSTable format name in %s cannot be null", factory.getClass().getCanonicalName()));

            if (!factory.name().matches("^[a-z]+$"))
                throw new ConfigurationException(String.format("SSTable format name for %s must be non-empty, lower-case letters only string", factory.getClass().getCanonicalName()));

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Set commitlog_disk_access_mode: auto when using commit log compression and/or encryption — Cassandra will resolve the safe mode
  2. Explicitly set commitlog_disk_access_mode: standard if you must pin the mode with compression/encryption enabled
  3. Disable commitlog compression/encryption if you have a hard requirement for mmap/direct access mode

Example fix

# before (cassandra.yaml)
commitlog_compression:
  - class_name: LZ4Compressor
commitlog_disk_access_mode: mmap
# after
commitlog_compression:
  - class_name: LZ4Compressor
commitlog_disk_access_mode: auto
Defensive patterns

Strategy: validation

Validate before calling

if (compressionEnabled && modeIsMmapOrDirect) throw new IllegalStateException("use auto with compression/encryption");

Try / catch

try { DatabaseDescriptor.daemonInitialization(); } catch (ConfigurationException e) { /* set auto */ }

Prevention

When it happens

Trigger: commitlog_compression enabled (e.g. LZ4) and/or an enabled encryption_context, while commitlog_disk_access_mode resolves to mmap or direct instead of standard/auto; the first branch (compressOrEncrypt && mode != standard) throws.

Common situations: Enabling commit log compression or at-rest encryption on a node already tuned with commitlog_disk_access_mode: mmap; defaults on older versions pinned to mmap then upgrading and turning on encryption.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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