apache/cassandra · error · ConfigurationException

phi_convict_threshold must be between 5 and 16, but was

Error message

phi_convict_threshold must be between 5 and 16, but was ${conf.phi_convict_threshold}

What it means

phi_convict_threshold feeds the Phi Accrual failure detector; Cassandra bounds it to the range [5, 16] so nodes neither flap on tiny jitter (too low) nor fail to convict dead peers for a long time (too high). applySimpleConfig throws ConfigurationException at startup when the configured value falls outside that range.

Solutions

Set `phi_convict_threshold` to a value within [5, 16] (default is 8) in cassandra.yaml.
Remove the override to use the default 8.
Address underlying network instability with tuning elsewhere (e.g. cross_dc_rtt_in_ms) rather than pushing the threshold out of bounds.

Example fix

// before (cassandra.yaml)
phi_convict_threshold: 2
// after (cassandra.yaml)
phi_convict_threshold: 8

Defensive patterns

Strategy: validation

Validate before calling

// Java, before toolInitialization()
double phi = /* configured phi_convict_threshold */;
if (phi < 5 || phi > 16)
    throw new IllegalArgumentException("phi_convict_threshold must be within [5,16], got " + phi);

Prevention

Keep phi_convict_threshold at the default 8 unless failure detection is measurably broken.
Clamp externally supplied values into [5,16] in config generators.
Don't interpret the threshold as a percentage or probability.

When it happens

Trigger: cassandra.yaml (or a programmatically provided Config) has `phi_convict_threshold` below 5 or above 16 — e.g. 1, 50, or a float like 20 — when DatabaseDescriptor.toolInitialization/applyAll runs.

Common situations: Operators tuning noisy-datacenter failure detection copying values from blog posts recommending 1-2; decimal/percent confusion (entering 0.5 or 50); automated config generators clamping incorrectly.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

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

        if (DiskAccessMode.auto == conf.compaction_read_disk_access_mode)
        {
            compactionReadDiskAccessMode = conf.disk_access_mode;
        }
        else if (DiskAccessMode.direct == conf.compaction_read_disk_access_mode)
        {
            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))));

View on GitHub (pinned to 88fd0f6a0e)