apache/pulsar · error · IllegalArgumentException

Invalid auto split/merge configuration: ${message}

Error message

Invalid auto split/merge configuration: ${message}

What it means

AutoScaleConfig.check is the shared guard for broker auto split/merge (scalable topic) settings. Each validated invariant (thresholds positive, split threshold above merge threshold for hysteresis, etc.) calls check; a violated condition yields an IllegalArgumentException prefixed 'Invalid auto split/merge configuration:'.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/service/scalable/AutoScaleConfig.java:255

        check(splitVsRebucketMinMsgRateIn >= 0,
                "splitVsRebucketMinMsgRateInThreshold must be >= 0");
        check(maxEntryBucketsPerSegment >= 1 && maxEntryBucketsPerSegment
                        <= EntryBucketSplits.MAX_BUCKETS,
                "maxEntryBucketsPerSegment must be in [1, " + EntryBucketSplits.MAX_BUCKETS + "]");
        check(splitMsgRateIn > mergeMsgRateIn,
                "splitMsgRateInThreshold must be > mergeMsgRateInThreshold (hysteresis)");
        check(splitBytesRateIn > mergeBytesRateIn,
                "splitBytesRateInThreshold must be > mergeBytesRateInThreshold (hysteresis)");
        check(splitMsgRateOut > mergeMsgRateOut,
                "splitMsgRateOutThreshold must be > mergeMsgRateOutThreshold (hysteresis)");
        check(splitBytesRateOut > mergeBytesRateOut,
                "splitBytesRateOutThreshold must be > mergeBytesRateOutThreshold (hysteresis)");
        return this;
    }

    private static void check(boolean condition, String message) {
        if (!condition) {
            throw new IllegalArgumentException("Invalid auto split/merge configuration: " + message);
        }
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Read the message suffix to identify which invariant failed and fix that config value
2. Keep splitBytesRateOutThreshold strictly greater than mergeBytesRateOutThreshold (hysteresis)
3. Validate config in a staging broker before rollout

Example fix

// before
mergeBytesRateOutThreshold = 80_000_000
splitBytesRateOutThreshold = 50_000_000
// after
mergeBytesRateOutThreshold = 40_000_000
splitBytesRateOutThreshold = 80_000_000  // split must exceed merge

if (cfg.getSplitBytesRateOutThreshold() <= cfg.getMergeBytesRateOutThreshold()) {
    throw new IllegalArgumentException("splitBytesRateOutThreshold must exceed mergeBytesRateOutThreshold");
}

try {
    AutoScaleConfig validated = autoScaleConfig.validated();
} catch (IllegalArgumentException e) {
    log.error("Autoscale config rejected: {}", e.getMessage());
}

When it happens

Trigger: Constructing/validating AutoScaleConfig via validated() with inconsistent values, e.g. splitBytesRateOutThreshold <= mergeBytesRateOutThreshold, non-positive thresholds, or other failed invariants.

Common situations: broker.conf or per-topic autoscale properties tuned by hand so split and merge thresholds cross; copy of defaults where only one threshold was scaled; units confusion (bytes/s vs entries/s).

Understand the failure class

Background: "Invalid configuration value" and "Unsupported/Unknown setting value" errors: why libraries reject your config strings, numbers, and types — this error's family across 30 libraries.

Related errors

• At least one of maxNumMessages, maxNumBytes, timeout must be
• Invalid time unit '<lastChar>'
• Broker doesn't allow forced deletion of namespaces
• Local cluster is not part of replicate cluster list
• ResourceGroupCreate: Invalid null ResourceGroup config

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/c47f4b527875b2bc. Report an issue: GitHub.