apache/cassandra · error · ConfigurationException

commitlog_disk_access_mode can not be set to direct when dir

Error message

commitlog_disk_access_mode can not be set to direct when direct IO is not supported by the file system.

What it means

validateCommitLogWriteDiskAccessMode enforces that commitlog_disk_access_mode = direct is only usable when the filesystem actually supports Direct IO (probed earlier against the commitlog directory). If Direct IO is unsupported (the pair's right flag is false) but the mode is set to direct, startup fails with this ConfigurationException.

Source

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

                                                                                                                                     : DiskAccessMode.legacy;
            }
        }

        if (providedDiskAccessMode == DiskAccessMode.legacy)
        {
            providedDiskAccessMode = compressOrEncrypt ? DiskAccessMode.standard : DiskAccessMode.mmap;
        }

        return Pair.create(providedDiskAccessMode, directIOSupported);
    }

    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);
        }
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set commitlog_disk_access_mode: auto and let Cassandra pick a supported mode
2. Explicitly choose commitlog_disk_access_mode: mmap (or standard where required) on filesystems without O_DIRECT
3. Move the commitlog onto a filesystem that supports Direct IO (ext4/XFS on a real block device) if you specifically need the direct mode

Example fix

# before (cassandra.yaml)
commitlog_disk_access_mode: direct
# after (on tmpfs/ZFS/NFS)
commitlog_disk_access_mode: auto

if ("direct".equals(yaml.get("commitlog_disk_access_mode")) && !directIOSupported) throw new IllegalStateException("use auto");

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

When it happens

Trigger: commitlog_disk_access_mode: direct (explicitly or resolved from config) while FileUtils.isDirectIOSupported on the commitlog directory returned false — e.g. tmpfs, older kernels, or filesystems without O_DIRECT support.

Common situations: Running Cassandra in containers with overlayfs/tmpfs commitlog mounts; ZFS or NFS mounts lacking O_DIRECT; setting 'direct' by copying tuning advice meant for XFS/ext4.

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

• Unable to determine block size for commit log directory: {}
• commitlog_directory must not be the same as any data_file_di
• local_system_data_file_directory must not be the same as the
• is missing and cassandra.storagedir system property is not
• commitlog_directory must be specified

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