apache/cassandra · error · ConfigurationException

concurrent_reads must be at least 2, but was ${conf.concurre

Error message

concurrent_reads must be at least 2, but was ${conf.concurrent_reads}

What it means

concurrent_reads controls the number of read stage worker threads; Cassandra requires at least 2 so the read pipeline can make progress even while one thread blocks. applySimpleConfig rejects values below 2 at startup with this ConfigurationException.

Source

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

            compactionReadDiskAccessMode = DiskAccessMode.direct;
        }
        else
        {
            throw new IllegalArgumentException("Unsupported disk access mode for compaction_read_disk_access_mode " +
                                               "(options: direct/auto) " + conf.compaction_read_disk_access_mode);
        }
        logger.info("compaction_read_disk_access_mode resolved to: {}", compactionReadDiskAccessMode);

        /* phi convict threshold for FailureDetector */
        if (conf.phi_convict_threshold < 5 || conf.phi_convict_threshold > 16)
        {
            throw new ConfigurationException("phi_convict_threshold must be between 5 and 16, but was " + conf.phi_convict_threshold, false);
        }

        /* Thread per pool */
        if (conf.concurrent_reads < 2)
        {
            throw new ConfigurationException("concurrent_reads must be at least 2, but was " + conf.concurrent_reads, false);
        }

        if (conf.concurrent_writes < 2 && TEST_FAIL_MV_LOCKS_COUNT.getString("").isEmpty())
        {
            throw new ConfigurationException("concurrent_writes must be at least 2, but was " + conf.concurrent_writes, false);
        }

        if (conf.concurrent_counter_writes < 2)
            throw new ConfigurationException("concurrent_counter_writes must be at least 2, but was " + conf.concurrent_counter_writes, false);

        if (conf.networking_cache_size == null)
            conf.networking_cache_size = new DataStorageSpec.IntMebibytesBound(Math.min(128, (int) (Runtime.getRuntime().maxMemory() / (16 * 1048576))));

        if (conf.file_cache_size == null)
            conf.file_cache_size = new DataStorageSpec.IntMebibytesBound(Math.min(512, (int) (Runtime.getRuntime().maxMemory() / (4 * 1048576))));

        // round down for SSDs and round up for spinning disks
        if (conf.file_cache_round_up == null)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Raise `concurrent_reads` to at least 2; the shipped default is 32 (16 x CPU cores in many builds).
Remove the override to use the default value.
Fix the config generator to clamp the computed value to a minimum of 2.

Example fix

// before (cassandra.yaml)
concurrent_reads: 1
// after (cassandra.yaml)
concurrent_reads: 32

Defensive patterns

Strategy: validation

Validate before calling

// Java, before toolInitialization()
int reads = /* configured concurrent_reads */;
if (reads < 2)
    throw new IllegalArgumentException("concurrent_reads must be >= 2, got " + reads);

Prevention

Clamp all concurrent_* pool values to >= 2 in any config generator.
Don't set pools to 0 or 1 to 'shrink' Cassandra on dev machines; use the defaults.
Validate cassandra.yaml with a startup smoke test in CI.

When it happens

Trigger: Setting `concurrent_reads: 0` or `concurrent_reads: 1` in cassandra.yaml (or passing such a Config programmatically) before DatabaseDescriptor.toolInitialization/applyAll.

Common situations: Aggressively shrinking thread pools on tiny test containers or dev laptops; config generators computing thread counts as 'cores - N' yielding 1 or 0; typos like concurrent_reads: 2_ (parsed low) or unset-derived zeros in templated YAML.

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/122d6fee5b15a88e. Report an issue: GitHub.