apache/cassandra · error · ConfigurationException

direct_write_buffer_size must be > 0 when background_write_d

Error message

direct_write_buffer_size must be > 0 when background_write_disk_access_mode is 'direct'. Got:

What it means

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.

Source

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

        if (getBackgroundWriteDiskAccessMode() == DiskAccessMode.direct)
            for (String dataDir : getAllDataFileLocations())
                paths.add(new File(dataDir).toPath());

        return paths;
    }

    @VisibleForTesting
    public static void initializeBackgroundWriteDiskAccessMode()
    {
        DiskAccessMode providedMode = conf.background_write_disk_access_mode;

        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;
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Set direct_write_buffer_size to a positive value (e.g. 16MiB or larger) in cassandra.yaml.
  2. If not using O_DIRECT, change disk_access_mode/background_write_disk_access_mode away from 'direct' instead of zeroing the buffer.
  3. Fix unit suffixes so the spec does not resolve to 0 bytes.

Example fix

# before (cassandra.yaml, with direct write mode)
direct_write_buffer_size: 0
# after
direct_write_buffer_size: 16MiB
Defensive patterns

Strategy: validation

Validate before calling

if (DatabaseDescriptor.getDiskAccessMode() == DiskAccessMode.direct || usesDirectWrites) {
    long bytes = conf.direct_write_buffer_size.toBytes();
    if (bytes <= 0) throw new IllegalStateException("direct_write_buffer_size must be > 0 for direct mode");
}

Type guard

boolean isValidDirectWriteBufferSize(DataStorageSpec spec) { return spec != null && spec.toBytes() > 0; }

Try / catch

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; }

Prevention

When it happens

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

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

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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