apache/cassandra · error · ConfigurationException

Unable to create instance of IAutoRepairTokenRangeSplitter

Error message

Unable to create instance of IAutoRepairTokenRangeSplitter

What it means

AutoRepairConfig.newAutoRepairTokenRangeSplitter wraps any exception from instantiating the configured IAutoRepairTokenRangeSplitter class (constructor with optional ConfigurationException argument, or fall-back no-arg constructor) into a ConfigurationException. The configured class cannot be loaded, has the wrong type, or its constructor fails.

Source

Thrown at src/java/org/apache/cassandra/repair/autorepair/AutoRepairConfig.java:422

            {
                // If token_range_splitter.class_name is not defined, just use default, this is for convenience.
                tokenRangeSplitterClass = AutoRepairConfig.DEFAULT_SPLITTER;
            }
            try
            {
                Map<String, String> parameters = parameterizedClass.parameters != null ? parameterizedClass.parameters : Collections.emptyMap();
                // first attempt to initialize with RepairType and Map arguments.
                return tokenRangeSplitterClass.getConstructor(RepairType.class, Map.class).newInstance(repairType, parameters);
            }
            catch (NoSuchMethodException nsme)
            {
                // fall back on no argument constructor.
                return tokenRangeSplitterClass.getConstructor().newInstance();
            }
        }
        catch (Exception ex)
        {
            throw new ConfigurationException("Unable to create instance of IAutoRepairTokenRangeSplitter", ex);
        }
    }

    // Options configures auto-repair behavior for a given repair type.
    // All fields can be modified dynamically.
    public static class Options implements Serializable
    {
        // defaultOptions defines the default auto-repair behavior when no overrides are defined
        @VisibleForTesting
        private static Map<AutoRepairConfig.RepairType, Options> defaultOptions;

        private static Map<AutoRepairConfig.RepairType, Options> initializeDefaultOptions()
        {
            Map<AutoRepairConfig.RepairType, Options> options = new EnumMap<>(AutoRepairConfig.RepairType.class);
            options.put(AutoRepairConfig.RepairType.FULL, getDefaultOptions());
            options.put(RepairType.INCREMENTAL, getDefaultOptions());
            options.put(RepairType.PREVIEW_REPAIRED, getDefaultOptions());

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Fix the class name in cassandra.yaml (default: org.apache.cassandra.repair.autorepair.FixedSplitTokenRangeSplitter)
Ensure the jar providing the splitter is on the Cassandra classpath
Implement IAutoRepairTokenRangeSplitter and provide a public no-arg constructor
Inspect the chained cause (ex) to distinguish ClassNotFound vs constructor failure

Example fix

# before
auto_repair:
  token_range_splitter: com.example.MySplitter
# after
auto_repair:
  token_range_splitter: org.apache.cassandra.repair.autorepair.FixedSplitTokenRangeSplitter

Defensive patterns

Strategy: validation

Validate before calling

String cls = config.autoRepairTokenRangeSplitter();
Class<?> c = Class.forName(cls);
if (!IAutoRepairTokenRangeSplitter.class.isAssignableFrom(c))
    throw new ConfigurationException(cls + " does not implement IAutoRepairTokenRangeSplitter");
c.getDeclaredConstructor(); // must exist

Try / catch

try { config.getTokenRangeSplitterInstance(repairType); }
catch (ConfigurationException e) {
    logger.error("Falling back to default splitter: {}", e.getCause(), e);
    config.setTokenRangeSplitter("org.apache.cassandra.repair.autorepair.FixedSplitTokenRangeSplitter");
}

Prevention

Copy the exact fully-qualified class name from provider docs
Ship the custom splitter jar in lib/ and verify with Class.forName smoke test
Keep a public no-arg constructor on custom splitters
Re-test custom splitters after every Cassandra upgrade

When it happens

Trigger: Setting auto_repair token_range_splitter (or per-repair-type splitter) to a class name that is missing from the classpath, does not implement IAutoRepairTokenRangeSplitter, lacks a suitable constructor, or whose constructor throws.

Common situations: Typo in the fully-qualified class name in cassandra.yaml; custom splitter jar missing from lib/ or classpath; custom splitter incompatible after upgrade; splitter constructor requiring an unavailable argument.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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