{"record":{"id":"d2e499546f92c5fc","repo":"apache/cassandra","slug":"phi-convict-threshold-must-be-between-5-and-16-bu","errorCode":null,"errorMessage":"phi_convict_threshold must be between 5 and 16, but was ${conf.phi_convict_threshold}","messagePattern":"phi_convict_threshold must be between 5 and 16, but was (.+?)","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/config/DatabaseDescriptor.java","lineNumber":722,"sourceCode":"        if (DiskAccessMode.auto == conf.compaction_read_disk_access_mode)\n        {\n            compactionReadDiskAccessMode = conf.disk_access_mode;\n        }\n        else if (DiskAccessMode.direct == conf.compaction_read_disk_access_mode)\n        {\n            compactionReadDiskAccessMode = DiskAccessMode.direct;\n        }\n        else\n        {\n            throw new IllegalArgumentException(\"Unsupported disk access mode for compaction_read_disk_access_mode \" +\n                                               \"(options: direct/auto) \" + conf.compaction_read_disk_access_mode);\n        }\n        logger.info(\"compaction_read_disk_access_mode resolved to: {}\", compactionReadDiskAccessMode);\n\n        /* phi convict threshold for FailureDetector */\n        if (conf.phi_convict_threshold < 5 || conf.phi_convict_threshold > 16)\n        {\n            throw new ConfigurationException(\"phi_convict_threshold must be between 5 and 16, but was \" + conf.phi_convict_threshold, false);\n        }\n\n        /* Thread per pool */\n        if (conf.concurrent_reads < 2)\n        {\n            throw new ConfigurationException(\"concurrent_reads must be at least 2, but was \" + conf.concurrent_reads, false);\n        }\n\n        if (conf.concurrent_writes < 2 && TEST_FAIL_MV_LOCKS_COUNT.getString(\"\").isEmpty())\n        {\n            throw new ConfigurationException(\"concurrent_writes must be at least 2, but was \" + conf.concurrent_writes, false);\n        }\n\n        if (conf.concurrent_counter_writes < 2)\n            throw new ConfigurationException(\"concurrent_counter_writes must be at least 2, but was \" + conf.concurrent_counter_writes, false);\n\n        if (conf.networking_cache_size == null)\n            conf.networking_cache_size = new DataStorageSpec.IntMebibytesBound(Math.min(128, (int) (Runtime.getRuntime().maxMemory() / (16 * 1048576))));","sourceCodeStart":704,"sourceCodeEnd":740,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/DatabaseDescriptor.java#L704-L740","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before (cassandra.yaml)\nphi_convict_threshold: 2\n// after (cassandra.yaml)\nphi_convict_threshold: 8","handlingStrategy":"validation","validationCode":"// Java, before toolInitialization()\ndouble phi = /* configured phi_convict_threshold */;\nif (phi < 5 || phi > 16)\n    throw new IllegalArgumentException(\"phi_convict_threshold must be within [5,16], got \" + phi);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["config","failure-detection","value-out-of-range","startup"],"backgroundTag":"value-out-of-range","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}