apache/cassandra · error · ConfigurationException

Unsupported disk access mode for background_write_disk_acces

Error message

Unsupported disk access mode for background_write_disk_access_mode (options: standard/direct):

What it means

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.

Source

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

        if (providedMode == DiskAccessMode.direct)
        {
            // DataStorageSpec already rejects negatives at parse time; zero is the remaining
            // nonsense value. The writer's Math.max would silently coerce it to minRequiredSize,
            // which masks a likely operator mistake — fail fast instead.
            if (conf.direct_write_buffer_size.toBytes() <= 0)
                throw new ConfigurationException("direct_write_buffer_size must be > 0 when background_write_disk_access_mode is 'direct'. " +
                                                 "Got: " + conf.direct_write_buffer_size, false);

            // Create the data directories up front (as we do for the commit log) so the kernel-bug 1057843
            // startup check can stat each O_DIRECT write target. Direct I/O support is validated separately
            // by the directio_support startup check.
            if (!toolInitialized)
                for (String dataDir : getAllDataFileLocations())
                    PathUtils.createDirectoriesIfNotExists(new File(dataDir).toPath());
        }
        else if (providedMode != DiskAccessMode.standard)
        {
            throw new ConfigurationException("Unsupported disk access mode for background_write_disk_access_mode " +
                                             "(options: standard/direct): " + providedMode, false);
        }

        backgroundWriteDiskAccessMode = providedMode;
    }

    public static String getSavedCachesLocation()
    {
        return conf.saved_caches_directory;
    }

    public static Set<InetAddressAndPort> getSeeds()
    {
        return ImmutableSet.<InetAddressAndPort>builder().addAll(seedProvider.getSeeds()).build();
    }

    public static SeedProvider getSeedProvider()
    {

View on GitHub (pinned to 88fd0f6a0e)

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

Example fix

// before (cassandra.yaml)
background_write_disk_access_mode: mmap
// after
background_write_disk_access_mode: direct

Defensive patterns

Strategy: validation

Validate before calling

String mode = config.background_write_disk_access_mode;
if (!"standard".equals(mode) && !"direct".equals(mode))
    throw new IllegalArgumentException("background_write_disk_access_mode must be standard or direct, got: " + mode);

Try / catch

try {
    DatabaseDescriptor.setBackgroundWriteDiskAccessMode(mode);
} catch (ConfigurationException e) {
    logger.error("Invalid background_write_disk_access_mode, falling back to standard", e);
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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