{"record":{"id":"828e87eda770628c","repo":"apache/cassandra","slug":"commitlog-disk-access-mode","errorCode":null,"errorMessage":"commitlog_disk_access_mode = ","messagePattern":"commitlog_disk_access_mode = ","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/config/DatabaseDescriptor.java","lineNumber":1917,"sourceCode":"\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\n    private static void validateSSTableFormatFactories(Iterable<SSTableFormat.Factory> factories)\n    {\n        Map<String, SSTableFormat.Factory> factoryByName = new HashMap<>();\n        for (SSTableFormat.Factory factory : factories)\n        {\n            if (factory.name() == null)\n                throw new ConfigurationException(String.format(\"SSTable format name in %s cannot be null\", factory.getClass().getCanonicalName()));\n\n            if (!factory.name().matches(\"^[a-z]+$\"))\n                throw new ConfigurationException(String.format(\"SSTable format name for %s must be non-empty, lower-case letters only string\", factory.getClass().getCanonicalName()));\n","sourceCodeStart":1899,"sourceCodeEnd":1935,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/DatabaseDescriptor.java#L1899-L1935","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set commitlog_disk_access_mode: auto when using commit log compression and/or encryption — Cassandra will resolve the safe mode","Explicitly set commitlog_disk_access_mode: standard if you must pin the mode with compression/encryption enabled","Disable commitlog compression/encryption if you have a hard requirement for mmap/direct access mode"],"exampleFix":"# before (cassandra.yaml)\ncommitlog_compression:\n  - class_name: LZ4Compressor\ncommitlog_disk_access_mode: mmap\n# after\ncommitlog_compression:\n  - class_name: LZ4Compressor\ncommitlog_disk_access_mode: auto","handlingStrategy":"validation","validationCode":"if (compressionEnabled && modeIsMmapOrDirect) throw new IllegalStateException(\"use auto with compression/encryption\");","typeGuard":null,"tryCatchPattern":"try { DatabaseDescriptor.daemonInitialization(); } catch (ConfigurationException e) { /* set auto */ }","preventionTips":["Use auto mode when compression or encryption is enabled"],"tags":["configuration","commitlog","compression","encryption"],"backgroundTag":"conflicting-config-options","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}