apache/pulsar · error · IllegalStateException

transactionCoordinatorScalableTopicsParallelism mismatch: th

Error message

transactionCoordinatorScalableTopicsParallelism mismatch: this broker is configured with ${partitionCount} but the cluster was initialized with ${stored}. The value is fixed at cluster bring-up and must be identical on every broker.

What it means

Error "transactionCoordinatorScalableTopicsParallelism mismatch: this broker is configured with ${partitionCount} but the cluster was initialized with ${stored}. The value is fixed at cluster bring-up and must be identical on every broker." thrown in apache/pulsar.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/transaction/coordinator/v5/TransactionCoordinatorV5.java:219

                checkParallelismMatches(existing.get().getValue());
            }
        } catch (IllegalStateException e) {
            throw e;
        } catch (Exception e) {
            // A racing create (BadVersion) or read-after-write resolves by re-reading and comparing.
            try {
                var after = store.get(TxnPaths.TXN_TC_PARALLELISM_PATH).get();
                after.ifPresent(r -> checkParallelismMatches(r.getValue()));
            } catch (Exception ignore) {
                log.warn().exception(e).log("Could not verify TC parallelism consistency; proceeding");
            }
        }
    }

    private void checkParallelismMatches(byte[] storedValue) {
        int stored = Integer.parseInt(new String(storedValue, java.nio.charset.StandardCharsets.UTF_8).trim());
        if (stored != partitionCount) {
            throw new IllegalStateException(
                    "transactionCoordinatorScalableTopicsParallelism mismatch: this broker is configured"
                            + " with " + partitionCount + " but the cluster was initialized with " + stored
                            + ". The value is fixed at cluster bring-up and must be identical on every"
                            + " broker.");
        }
    }

    /** Stop the sweeps and release every leader-election lease. Idempotent. */
    public synchronized void close() {
        closed = true;
        if (sweepExecutor != null) {
            sweepExecutor.shutdownNow();
            sweepExecutor = null;
        }
        elections.values().forEach(e -> e.asyncClose().exceptionally(ex -> {
            log.warn().exception(ex).log("v5 TC election close failed");
            return null;
        }));

View on GitHub (pinned to 820761864e)

Solutions

1. Set transactionCoordinatorScalableTopicsParallelism to the value the cluster was initialized with on every broker
2. Bring up a new cluster with the intended value if a change is unavoidable (it cannot be changed in place)

When it happens

Trigger: Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/transaction/coordinator/v5/TransactionCoordinatorV5.java:219 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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