What causes "Missing repair sub-option '%s'" in apache/cassandra?

Supply ALL auto repair sub-options defined by the Option enum in the map

apache/cassandra · error · ConfigurationException

Missing repair sub-option '%s'

Error message

Missing repair sub-option '%s'

What it means

AutoRepairParams.validate requires every Option enum key to be present in the options map; if any is missing it throws ConfigurationException. Unlike most Cassandra option maps, auto repair params are all-or-nothing: a partial map is treated as an invalid configuration rather than merged with defaults.

Source

Thrown at src/java/org/apache/cassandra/schema/AutoRepairParams.java:109

    {
        String option = LocalizeString.toLowerCaseLocalized(type.toString()) + "_enabled";
        String enabled = options.getOrDefault(option, DEFAULT_OPTIONS.get(option));
        return Boolean.parseBoolean(enabled);
    }

    public int priority()
    {
        String priority = options.getOrDefault(Option.PRIORITY.toString(), DEFAULT_OPTIONS.get(Option.PRIORITY.toString()));
        return Integer.parseInt(priority);
    }

    public void validate()
    {
        for (Option option : Option.values())
        {
            if (!options.containsKey(LocalizeString.toLowerCaseLocalized(option.toString())))
            {
                throw new ConfigurationException(format("Missing repair sub-option '%s'", option));
            }
        }
        if (options.get(LocalizeString.toLowerCaseLocalized(Option.FULL_ENABLED.toString())) != null && !isValidBoolean(options.get(LocalizeString.toLowerCaseLocalized(Option.FULL_ENABLED.toString()))))
        {
            throw new ConfigurationException(format("Invalid value %s for '%s' repair sub-option - must be a boolean",
                                                    options.get(LocalizeString.toLowerCaseLocalized(Option.FULL_ENABLED.toString())),
                                                    Option.FULL_ENABLED));
        }
        if (options.get(LocalizeString.toLowerCaseLocalized(Option.INCREMENTAL_ENABLED.toString())) != null && !isValidBoolean(options.get(LocalizeString.toLowerCaseLocalized(Option.INCREMENTAL_ENABLED.toString()))))
        {
            throw new ConfigurationException(format("Invalid value %s for '%s' repair sub-option - must be a boolean",
                                                    options.get(LocalizeString.toLowerCaseLocalized(Option.INCREMENTAL_ENABLED.toString())),
                                                    Option.INCREMENTAL_ENABLED));
        }
        if (options.get(LocalizeString.toLowerCaseLocalized(Option.PREVIEW_REPAIRED_ENABLED.toString())) != null && !isValidBoolean(options.get(LocalizeString.toLowerCaseLocalized(Option.PREVIEW_REPAIRED_ENABLED.toString()))))
        {
            throw new ConfigurationException(format("Invalid value %s for '%s' repair sub-option - must be a boolean",
                                                    options.get(LocalizeString.toLowerCaseLocalized(Option.PREVIEW_REPAIRED_ENABLED.toString())),

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Supply ALL auto repair sub-options defined by the Option enum in the map
Read the current full map (e.g. from system_schema) and re-issue the complete set with your change
Use a driver/tool that builds the complete options map

Example fix

// before
WITH auto_repair = {'full_enabled': 'true'}
// after
WITH auto_repair = {'full_enabled': 'true', 'incremental_enabled': 'false', 'preview_repaired_enabled': 'false', 'priority': '1'}

Defensive patterns

Strategy: validation

Validate before calling

for (Option o : Option.values())
    if (!autoRepairOptions.containsKey(o.toString().toLowerCase()))
        throw new IllegalArgumentException("Missing auto repair sub-option: " + o);

Try / catch

try { params.validate(); } catch (ConfigurationException e) { if (e.getMessage().startsWith("Missing repair sub-option")) { /* fill in all sub-options and re-apply */ } else throw e; }

Prevention

Always write the complete auto_repair map, never a partial one
Read the existing map from system_schema and merge before ALTERing
Use a schema-management tool that emits full option sets

When it happens

Trigger: CREATE/ALTER TABLE with auto_repair = {'full_enabled':'true'} supplying only some of the required sub-options (full_enabled, incremental_enabled, preview_repaired_enabled, priority, ...).

Common situations: Hand-written CQL that lists just one flag; migration scripts generating partial maps; tools that update a single option without rewriting the whole map.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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