{"record":{"id":"a22fe20fdb7320e8","repo":"apache/cassandra","slug":"commitlog-disk-access-mode-can-not-be-set-to-direc","errorCode":null,"errorMessage":"commitlog_disk_access_mode can not be set to direct when direct IO is not supported by the file system.","messagePattern":"commitlog_disk_access_mode can not be set to direct when direct IO is not supported by the file system\\.","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/config/DatabaseDescriptor.java","lineNumber":1906,"sourceCode":"                                                                                                                                     : DiskAccessMode.legacy;\n            }\n        }\n\n        if (providedDiskAccessMode == DiskAccessMode.legacy)\n        {\n            providedDiskAccessMode = compressOrEncrypt ? DiskAccessMode.standard : DiskAccessMode.mmap;\n        }\n\n        return Pair.create(providedDiskAccessMode, directIOSupported);\n    }\n\n    private static void validateCommitLogWriteDiskAccessMode(Pair<DiskAccessMode, Boolean> accessModeDirectIoPair) throws ConfigurationException\n    {\n        boolean compressOrEncrypt = getCommitLogCompression() != null || (getEncryptionContext() != null && getEncryptionContext().isEnabled());\n\n        if (!accessModeDirectIoPair.right && accessModeDirectIoPair.left == DiskAccessMode.direct)\n        {\n            throw new ConfigurationException(\"commitlog_disk_access_mode can not be set to direct when direct IO is not supported by the file system.\");\n        }\n        else if (compressOrEncrypt && accessModeDirectIoPair.left != DiskAccessMode.standard)\n        {\n            String with;\n            if (null != getCommitLogCompression() && (null != getEncryptionContext() && getEncryptionContext().isEnabled()))\n                with = \"compression or encryption\";\n            else if (null != getCommitLogCompression())\n                with = \"compression\";\n            else\n                with = \"encryption\";\n            throw new ConfigurationException(\"commitlog_disk_access_mode = \" + accessModeDirectIoPair.left + \" is not supported with \" + with + \". Please use 'auto' when unsure.\", false);\n        }\n        else if (!compressOrEncrypt && accessModeDirectIoPair.left != DiskAccessMode.mmap && accessModeDirectIoPair.left != DiskAccessMode.direct)\n        {\n            throw new ConfigurationException(\"commitlog_disk_access_mode = \" + accessModeDirectIoPair.left + \" is not supported. Please use 'auto' when unsure.\", false);\n        }\n    }\n","sourceCodeStart":1888,"sourceCodeEnd":1924,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/DatabaseDescriptor.java#L1888-L1924","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set commitlog_disk_access_mode: auto and let Cassandra pick a supported mode","Explicitly choose commitlog_disk_access_mode: mmap (or standard where required) on filesystems without O_DIRECT","Move the commitlog onto a filesystem that supports Direct IO (ext4/XFS on a real block device) if you specifically need the direct mode"],"exampleFix":"# before (cassandra.yaml)\ncommitlog_disk_access_mode: direct\n# after (on tmpfs/ZFS/NFS)\ncommitlog_disk_access_mode: auto","handlingStrategy":"validation","validationCode":"if (\"direct\".equals(yaml.get(\"commitlog_disk_access_mode\")) && !directIOSupported) throw new IllegalStateException(\"use auto\");","typeGuard":null,"tryCatchPattern":"try { DatabaseDescriptor.daemonInitialization(); } catch (ConfigurationException e) { /* use auto mode */ }","preventionTips":["Default to commitlog_disk_access_mode: auto"],"tags":["configuration","commitlog","direct-io","filesystem"],"backgroundTag":"invalid-config-value","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}