{"record":{"id":"a836dbe7055f8179","repo":"apache/cassandra","slug":"unsupported-disk-access-mode-for-background-write","errorCode":null,"errorMessage":"Unsupported disk access mode for background_write_disk_access_mode (options: standard/direct): ","messagePattern":"Unsupported disk access mode for background_write_disk_access_mode \\(options: standard/direct\\): ","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/config/DatabaseDescriptor.java","lineNumber":3555,"sourceCode":"        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\n    public static String getSavedCachesLocation()\n    {\n        return conf.saved_caches_directory;\n    }\n\n    public static Set<InetAddressAndPort> getSeeds()\n    {\n        return ImmutableSet.<InetAddressAndPort>builder().addAll(seedProvider.getSeeds()).build();\n    }\n\n    public static SeedProvider getSeedProvider()\n    {","sourceCodeStart":3537,"sourceCodeEnd":3573,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/DatabaseDescriptor.java#L3537-L3573","documentation":"Cassandra throws this ConfigurationException when background_write_disk_access_mode is set to a value other than 'standard' or 'direct'. The background write disk access mode controls how Cassandra performs I/O for background writes (memtable flushing), and only these two modes are supported for this setting.","triggerScenarios":"Setting background_write_disk_access_mode in cassandra.yaml to an unsupported value such as 'mmap' or 'auto', or calling DatabaseDescriptor.setBackgroundWriteDiskAccessMode(DiskAccessMode.mmap) at runtime via JMX/config mutation.","commonSituations":"Operators copy the disk_access_mode value (which allows mmap/auto) into background_write_disk_access_mode, or upgrade across Cassandra versions where the set of valid modes for this option was narrowed to standard/direct.","solutions":["Edit cassandra.yaml and set background_write_disk_access_mode to 'standard' or 'direct'","Check the actual value: the exception message prints the offending mode; fix typos/case","Use DiskAccessMode.standard or DiskAccessMode.direct when calling setBackgroundWriteDiskAccessMode programmatically"],"exampleFix":"// before (cassandra.yaml)\nbackground_write_disk_access_mode: mmap\n// after\nbackground_write_disk_access_mode: direct","handlingStrategy":"validation","validationCode":"String mode = config.background_write_disk_access_mode;\nif (!\"standard\".equals(mode) && !\"direct\".equals(mode))\n    throw new IllegalArgumentException(\"background_write_disk_access_mode must be standard or direct, got: \" + mode);","typeGuard":null,"tryCatchPattern":"try {\n    DatabaseDescriptor.setBackgroundWriteDiskAccessMode(mode);\n} catch (ConfigurationException e) {\n    logger.error(\"Invalid background_write_disk_access_mode, falling back to standard\", e);\n}","preventionTips":["Only use 'standard' or 'direct' for background_write_disk_access_mode","Never copy disk_access_mode values (mmap/auto) into this setting","Validate cassandra.yaml values before a rolling restart"],"tags":["configuration","storage","startup"],"backgroundTag":"invalid-enum-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"}