apache/cassandra · error · ConfigurationException

Invalid overlap inclusion method

Error message

Invalid overlap inclusion method %s. The valid options are %s.

What it means

The overlap inclusion method option must be one of the Overlaps.InclusionMethod enum values; validateOptions rejects any other string. This option controls how sstable overlap is computed for unified compaction (e.g. SINGLE vs TRANSITIVE).

Solutions

Use one of the exact values listed in the error message from Overlaps.InclusionMethod.values().
Check the enum definition in Overlaps.java for the valid constants for your Cassandra version.
Remove the option to use the default inclusion method.

Example fix

// before
'overlap_inclusion_method': 'transitive_overlap'
// after
'overlap_inclusion_method': 'TRANSITIVE'

Defensive patterns

Strategy: validation

Validate before calling

String s = opts.get("overlap_inclusion_method");
if (s != null) Overlaps.InclusionMethod.valueOf(s.toUpperCase(Locale.ROOT)); // throws if invalid

Try / catch

try { createTable(withOptions); } catch (ConfigurationException e) { logger.error("Bad overlap_inclusion_method, valid: {}", Arrays.toString(Overlaps.InclusionMethod.values())); }

Prevention

Copy enum constant names from Overlaps.InclusionMethod, never type them from memory
Parse the valid options out of the ConfigurationException message when debugging
Pin config templates to a Cassandra version — enum options vary between versions

When it happens

Trigger: Setting compaction option 'overlap_inclusion_method' (or similar Overlaps option) to a string not in Arrays.toString(Overlaps.InclusionMethod.values()) during validateOptions; valueOf on the uppercased string throws IllegalArgumentException.

Common situations: Misspelling an enum constant ('transitive' vs correct casing is fine since it's uppercased, but 'transitve' is not); using an option name valid in a different Cassandra version.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

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

                                                               s,
                                                               EXPIRED_SSTABLE_CHECK_FREQUENCY_SECONDS_OPTION),
                                                 e);
            }
        }

        validateBoolean(options, ALLOW_UNSAFE_AGGRESSIVE_SSTABLE_EXPIRATION_OPTION);
        validateBoolean(options, PARALLELIZE_OUTPUT_SHARDS_OPTION);

        s = options.remove(OVERLAP_INCLUSION_METHOD_OPTION);
        if (s != null)
        {
            try
            {
                Overlaps.InclusionMethod.valueOf(toUpperCaseLocalized(s));
            }
            catch (IllegalArgumentException e)
            {
                throw new ConfigurationException(String.format("Invalid overlap inclusion method %s. The valid options are %s.",
                                                               s,
                                                               Arrays.toString(Overlaps.InclusionMethod.values())));
            }
        }

        s = options.remove(MIN_SSTABLE_SIZE_OPTION);
        if (s != null)
        {
            try
            {
                long sizeInBytes = FBUtilities.parseHumanReadableBytes(s);
                // zero is a valid option to disable feature
                if (sizeInBytes < 0)
                    throw new ConfigurationException(String.format("Invalid configuration, %s should be greater than or equal to 0 (zero)",
                                                                   MIN_SSTABLE_SIZE_OPTION));
                long limit = (long) Math.ceil(targetSSTableSize * INVERSE_SQRT_2);
                if (sizeInBytes >= limit)
                    throw new ConfigurationException(String.format("Invalid configuration, %s (%s) should be less than 70%% of the targetSSTableSize (%s)",

View on GitHub (pinned to 88fd0f6a0e)