apache/cassandra · error · ConfigurationException

Invalid configuration, %s should be positive: %d

Error message

Invalid configuration, %s should be positive: %d

What it means

UnifiedCompactionStrategy's Controller.validateOptions parses base_shard_count and requires a strictly positive integer, since the number of shards per level must divide data into at least one shard. Zero or negative values throw ConfigurationException with the parsed number.

Source

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

    }

    public static Map<String, String> validateOptions(Map<String, String> options) throws ConfigurationException
    {
        options = new HashMap<>(options);
        String s;

        s = options.remove(SCALING_PARAMETERS_OPTION);
        if (s != null)
            parseScalingParameters(s);

        s = options.remove(BASE_SHARD_COUNT_OPTION);
        if (s != null)
        {
            try
            {
                int numShards = Integer.parseInt(s);
                if (numShards <= 0)
                    throw new ConfigurationException(String.format("Invalid configuration, %s should be positive: %d",
                                                                   BASE_SHARD_COUNT_OPTION,
                                                                   numShards));
            }
            catch (NumberFormatException e)
            {
                throw new ConfigurationException(String.format("%s is not a parsable int (base10) for %s",
                                                               s,
                                                               BASE_SHARD_COUNT_OPTION), e);
            }
        }

        // preserve the configuration for later use during min_sstable_size.
        long targetSSTableSize = DEFAULT_TARGET_SSTABLE_SIZE;
        s = options.remove(TARGET_SSTABLE_SIZE_OPTION);
        if (s != null)
        {
            try
            {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set base_shard_count to a positive integer, e.g. '4'
2. Remove the option to use the default (1 shard)
3. Choose shard counts based on expected data size per node per level
4. Catch ConfigurationException when applying table options

Example fix

// before
'base_shard_count': '0'
// after
'base_shard_count': '4'

if (opts.containsKey("base_shard_count") && Integer.parseInt(opts.get("base_shard_count").trim()) <= 0)
    throw new IllegalArgumentException("base_shard_count must be a positive integer");

static boolean isPositiveInt(String s) { if (s == null) return false; try { return Integer.parseInt(s.trim()) > 0; } catch (NumberFormatException e) { return false; } }

try {
    session.execute(alterStmt);
} catch (RuntimeException e) {
    if (e.getMessage().contains("should be positive")) { /* fix base_shard_count */ }
    throw e;
}

When it happens

Trigger: validateOptions with base_shard_count='0', '-4', or any value that parses as int but is <= 0 (non-numeric values hit error 888 instead).

Common situations: Setting base_shard_count to 0 believing it means 'auto' or 'disabled'; negative sentinels from tooling; copy-paste from configs of other strategies.

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

• Scaling parameter %s must match %s
• Fan factor cannot be lower than 2 in %s
• %s is not a parsable int (base10) for %s
• %s %s is out of range of Long.
• concurrent_compactors should be strictly greater than 0, but

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