{"record":{"id":"08042a63a0528748","repo":"apache/cassandra","slug":"direct-write-buffer-size-must-be-0-when-backgrou","errorCode":null,"errorMessage":"direct_write_buffer_size must be > 0 when background_write_disk_access_mode is 'direct'. Got: ","messagePattern":"direct_write_buffer_size must be > 0 when background_write_disk_access_mode is 'direct'\\. Got: ","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/config/DatabaseDescriptor.java","lineNumber":3543,"sourceCode":"        if (getBackgroundWriteDiskAccessMode() == DiskAccessMode.direct)\n            for (String dataDir : getAllDataFileLocations())\n                paths.add(new File(dataDir).toPath());\n\n        return paths;\n    }\n\n    @VisibleForTesting\n    public static void initializeBackgroundWriteDiskAccessMode()\n    {\n        DiskAccessMode providedMode = conf.background_write_disk_access_mode;\n\n        if (providedMode == DiskAccessMode.direct)\n        {\n            // DataStorageSpec already rejects negatives at parse time; zero is the remaining\n            // nonsense value. The writer's Math.max would silently coerce it to minRequiredSize,\n            // which masks a likely operator mistake — fail fast instead.\n            if (conf.direct_write_buffer_size.toBytes() <= 0)\n                throw new ConfigurationException(\"direct_write_buffer_size must be > 0 when background_write_disk_access_mode is 'direct'. \" +\n                                                 \"Got: \" + conf.direct_write_buffer_size, false);\n\n            // Create the data directories up front (as we do for the commit log) so the kernel-bug 1057843\n            // startup check can stat each O_DIRECT write target. Direct I/O support is validated separately\n            // by the directio_support startup check.\n            if (!toolInitialized)\n                for (String dataDir : getAllDataFileLocations())\n                    PathUtils.createDirectoriesIfNotExists(new File(dataDir).toPath());\n        }\n        else if (providedMode != DiskAccessMode.standard)\n        {\n            throw new ConfigurationException(\"Unsupported disk access mode for background_write_disk_access_mode \" +\n                                             \"(options: standard/direct): \" + providedMode, false);\n        }\n\n        backgroundWriteDiskAccessMode = providedMode;\n    }\n","sourceCodeStart":3525,"sourceCodeEnd":3561,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/DatabaseDescriptor.java#L3525-L3561","documentation":"During startup initialization with disk_access_mode 'direct' (O_DIRECT writes), DatabaseDescriptor requires direct_write_buffer_size to be strictly positive. Zero is the remaining nonsense value after parse-time negative rejection; the writer would otherwise silently coerce it to a minimum size via Math.max, masking an operator mistake, so a ConfigurationException is thrown instead.","triggerScenarios":"Starting Cassandra (or running the config initialization path) with background_write_disk_access_mode/direct writes enabled while conf.direct_write_buffer_size resolves to <= 0 bytes, e.g. direct_write_buffer_size: 0 in cassandra.yaml.","commonSituations":"Operators zeroing the buffer to 'disable' sizing while using O_DIRECT; unit mistakes (0KiB/0MiB) in cassandra.yaml; template configs copied between direct and non-direct modes.","solutions":["Set direct_write_buffer_size to a positive value (e.g. 16MiB or larger) in cassandra.yaml.","If not using O_DIRECT, change disk_access_mode/background_write_disk_access_mode away from 'direct' instead of zeroing the buffer.","Fix unit suffixes so the spec does not resolve to 0 bytes."],"exampleFix":"# before (cassandra.yaml, with direct write mode)\ndirect_write_buffer_size: 0\n# after\ndirect_write_buffer_size: 16MiB","handlingStrategy":"validation","validationCode":"if (DatabaseDescriptor.getDiskAccessMode() == DiskAccessMode.direct || usesDirectWrites) {\n    long bytes = conf.direct_write_buffer_size.toBytes();\n    if (bytes <= 0) throw new IllegalStateException(\"direct_write_buffer_size must be > 0 for direct mode\");\n}","typeGuard":"boolean isValidDirectWriteBufferSize(DataStorageSpec spec) { return spec != null && spec.toBytes() > 0; }","tryCatchPattern":"try { DatabaseDescriptor.daemonInitialization(); } catch (ConfigurationException e) { if (e.getMessage().contains(\"direct_write_buffer_size\")) { log.error(\"Fix cassandra.yaml: direct_write_buffer_size must be > 0 in direct mode\"); System.exit(1); } throw e; }","preventionTips":["Never set direct_write_buffer_size to 0 when using O_DIRECT write modes","Validate cassandra.yaml unit suffixes (KiB/MiB) before deployment","Run a config-only startup validation in CI for direct-mode clusters"],"tags":["configuration","startup","direct-io"],"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"}