apache/cassandra · error · ConfigurationException

index_summary_capacity option was set incorrectly to

Error message

index_summary_capacity option was set incorrectly to '<value>', it should be a non-negative integer.

What it means

Thrown when index_summary_capacity resolves to a negative mebibyte value. Cassandra computes the default as max(1, 5% of heap) when unset; an explicit conf.index_summary_capacity value that parses but is negative fails this guard in applySimpleConfig.

Solutions

  1. Set index_summary_capacity to a non-negative integer mebibyte value (e.g. 128MiB) or remove the key to auto-size to 5% of heap.
  2. Re-run startup after correcting cassandra.yaml.

Example fix

# before
index_summary_capacity: -128MiB
# after
index_summary_capacity: 128MiB
Defensive patterns

Strategy: validation

Validate before calling

Object v = yaml.get("index_summary_capacity");
if (v != null && String.valueOf(v).trim().startsWith("-"))
    throw new IllegalArgumentException("index_summary_capacity must be a non-negative integer");

Type guard

boolean isValidIndexSummaryCapacity(Object v) {
    return v == null || (v instanceof Number && ((Number) v).longValue() >= 0);
}

Try / catch

try {
    DatabaseDescriptor.applySimpleConfig();
} catch (ConfigurationException e) {
    if (e.getMessage().contains("index_summary_capacity"))
        logger.error("Set index_summary_capacity to non-negative MiB value: {}", e.getMessage());
}

Prevention

When it happens

Trigger: cassandra.yaml has index_summary_capacity set to a negative storage bound (e.g. -20MiB). Parsing to a negative LongMebibytesBound passes the initial toMebibytes() conversion but fails the < 0 check.

Common situations: Sign errors in hand-edited yaml; automated config generation producing negative capacity; misunderstanding of the option's unit (mebibytes, not percent).

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/3203215a53c781b4. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/config/DatabaseDescriptor.java:1103

            if (consensusMigrationCacheSizeInMiB < 0)
                throw new NumberFormatException(); // to escape duplicating error message
        }
        catch (NumberFormatException e)
        {
            throw new ConfigurationException("consensus_migration_cache_size option was set incorrectly to '"
                                             + conf.consensus_migration_cache_size + "', supported values are <integer> >= 0.", false);
        }

        // we need this assignment for the Settings virtual table - CASSANDRA-17735
        conf.counter_cache_size = new DataStorageSpec.LongMebibytesBound(counterCacheSizeInMiB);

        // if set to empty/"auto" then use 5% of Heap size
        indexSummaryCapacityInMiB = (conf.index_summary_capacity == null)
                                    ? Math.max(1, (int) (Runtime.getRuntime().totalMemory() * 0.05 / 1024 / 1024))
                                    : conf.index_summary_capacity.toMebibytes();

        if (indexSummaryCapacityInMiB < 0)
            throw new ConfigurationException("index_summary_capacity option was set incorrectly to '"
                                             + conf.index_summary_capacity.toString() + "', it should be a non-negative integer.", false);

        // we need this assignment for the Settings virtual table - CASSANDRA-17735
        conf.index_summary_capacity = new DataStorageSpec.LongMebibytesBound(indexSummaryCapacityInMiB);

        if (conf.user_defined_functions_fail_timeout.toMilliseconds() < conf.user_defined_functions_warn_timeout.toMilliseconds())
            throw new ConfigurationException("user_defined_functions_warn_timeout must less than user_defined_function_fail_timeout", false);

        if (!conf.allow_insecure_udfs && !conf.user_defined_functions_threads_enabled)
            throw new ConfigurationException("To be able to set enable_user_defined_functions_threads: false you need to set allow_insecure_udfs: true - this is an unsafe configuration and is not recommended.");

        if (conf.allow_extra_insecure_udfs)
            logger.warn("Allowing java.lang.System.* access in UDFs is dangerous and not recommended. Set allow_extra_insecure_udfs: false to disable.");

        if (conf.scripted_user_defined_functions_enabled)
            throw new ConfigurationException("JavaScript user-defined functions were removed in CASSANDRA-18252. " +
                                             "Hooks are planned to be introduced as part of CASSANDRA-17280");

View on GitHub (pinned to 88fd0f6a0e)