apache/pulsar · error · IllegalArgumentException

Invalid auto split/merge configuration

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:'.

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…
• Invalid time unit
• Additional servlets ` ` does NOT provide an additional…
• Authentication method missing
• Both externalExecutorProvider and internalExecutorProvider…

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

Appendix: 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)