apache/cassandra · error · ConfigurationException

should either be 'true' or 'false', not

Error message

%s should either be 'true' or 'false', not %s

What it means

The controller's validateBoolean helper checks boolean compaction options (e.g. 'unsafe_aggressive_sstable_expiration'). The value must be the literal string 'true' or 'false' (case-insensitive). Any other string causes a ConfigurationException naming the option and offending value.

Solutions

  1. Change the value to 'true' or 'false' exactly (case-insensitive, no surrounding whitespace).
  2. Remove the option to use the default.
  3. If generating config from scripts, coerce yes/1/on to true before writing the option.

Example fix

// before
compaction = {'class': 'UnifiedCompactionStrategy', 'unsafe_aggressive_sstable_expiration': 'yes'};
// after
compaction = {'class': 'UnifiedCompactionStrategy', 'unsafe_aggressive_sstable_expiration': 'true'};
Defensive patterns

Strategy: validation

Validate before calling

for (String b : List.of("unsafe_aggressive_sstable_expiration")) {
    String v = options.get(b);
    if (v != null && !v.equalsIgnoreCase("true") && !v.equalsIgnoreCase("false"))
        throw new IllegalArgumentException(b + " must be 'true' or 'false': " + v);
}

Try / catch

try { strategy.validateOptions(opts); } catch (ConfigurationException e) { logger.error("Bad boolean option: {}", e.getMessage()); }

Prevention

When it happens

Trigger: Calling validateOptions (via table compaction options) with a boolean option set to values like 'yes', '1', 'on', or an empty string.

Common situations: Configs ported from systems that accept yes/1/on, shell scripts generating 'TRUE ' with stray whitespace, or hand-edited cassandra schema.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/db/compaction/unified/Controller.java:677

            }
            catch (NumberFormatException e)
            {
                throw new ConfigurationException(String.format("%s is not a valid number between 0 and 1: %s",
                                                               SSTABLE_GROWTH_OPTION,
                                                               e.getMessage()),
                                                 e);
            }
        }

        return options;
    }

    private static void validateBoolean(Map<String, String> options, String option)
    {
        String s;
        s = options.remove(option);
        if (s != null && !s.equalsIgnoreCase("true") && !s.equalsIgnoreCase("false")) {
            throw new ConfigurationException(String.format("%s should either be 'true' or 'false', not %s",
                    option, s));
        }
    }

    // The methods below are implemented here (rather than directly in UCS) to aid testability.

    public double getBaseSstableSize(int F)
    {
        // The compaction hierarchy should start at a minimum size which is close to the typical flush size, with
        // some leeway to make sure we don't overcompact when flushes end up a little smaller.
        // The leeway should be less than 1/F, though, to make sure we don't overshoot the boundary combining F-1
        // sources instead of F.
        // Note that while we have not had flushes, the size will be 0 and we will use 1MB as the flush size. With
        // fixed and positive W this should not hurt us, as the hierarchy will be in multiples of F and will still
        // result in the same buckets, but for negative W or hybrid strategies this may cause temporary overcompaction.
        // If this is a concern, the flush size override should be used to avoid it until DB-4401.
        return Math.max(1 << 20, getFlushSizeBytes()) * (1.0 - 0.9 / F);
    }

View on GitHub (pinned to 88fd0f6a0e)