apache/pulsar · error · RestException

This Broker is not configured with transactionCoordinatorEna

Error message

This Broker is not configured with transactionCoordinatorEnabled=true.

What it means

HTTP 503 SERVICE_UNAVAILABLE from checkTransactionCoordinatorEnabled: the broker is not configured with transactionCoordinatorEnabled=true, so all transaction coordinator admin endpoints refuse to operate. It is a configuration guard, not a transient outage.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/TransactionsBase.java:523

            CompletableFuture<Optional<Topic>> topicFuture = pulsar().getBrokerService()
                    .getTopics().get(topicName.toString());
            if (topicFuture == null) {
                return FutureUtil.failedFuture(new RestException(NOT_FOUND,
                        String.format("Topic not found %s", topicName.toString())));
            }
            return topicFuture.thenCompose(optionalTopic -> {
                if (!optionalTopic.isPresent()) {
                    return FutureUtil.failedFuture(new RestException(NOT_FOUND,
                            String.format("Topic not found %s", topicName.toString())));
                }
                return CompletableFuture.completedFuture((PersistentTopic) optionalTopic.get());
            });
        });
    }

    protected void checkTransactionCoordinatorEnabled() {
        if (!pulsar().getConfig().isTransactionCoordinatorEnabled()) {
           throw new RestException(SERVICE_UNAVAILABLE,
                    "This Broker is not configured with transactionCoordinatorEnabled=true.");
        }
    }

    protected void validateTopicName(String tenant, String namespace, String encodedTopic) {
        String topic = Codec.decode(encodedTopic);
        try {
            this.namespaceName = NamespaceName.get(tenant, namespace);
            this.topicName = TopicName.get(TopicDomain.persistent.toString(), namespaceName, topic);
        } catch (IllegalArgumentException e) {
            log.warn()
                    .attr("domain", domain())
                    .attr("tenant", tenant)
                    .attr("namespace", namespace)
                    .attr("topic", topic)
                    .exception(e)
                    .log("Failed to validate topic name");
            throw new RestException(Response.Status.PRECONDITION_FAILED, "Topic name is not valid");

View on GitHub (pinned to 820761864e)

Solutions

Set transactionCoordinatorEnabled=true in broker.conf (or via environment variable PULSAR_PREFIX_transactionCoordinatorEnabled for k8s) and restart the broker.
Confirm the request targets a broker/cluster with transactions enabled; check GET /admin/v2/brokers/configuration.
If transactions are not needed, stop calling the transaction coordinator admin endpoints.

Example fix

// broker.conf before
# transactionCoordinatorEnabled not set (defaults to false)
// after
transactionCoordinatorEnabled=true

Defensive patterns

Strategy: validation

Validate before calling

// Check broker config before using transaction admin APIs
boolean txEnabled = admin.brokers().getRuntimeConfigurations().entrySet().stream()
    .anyMatch(e -> e.getKey().equals("transactionCoordinatorEnabled")
        && Boolean.parseBoolean(String.valueOf(e.getValue())));
if (!txEnabled) {
    throw new IllegalStateException("Broker must set transactionCoordinatorEnabled=true");
}

Try / catch

try {
    admin.transactions().scaleTransactionCoordinators(replicas);
} catch (PulsarAdminException e) {
    if (e.getStatusCode() == 503) {
        throw new IllegalStateException("Enable transactionCoordinatorEnabled=true on the broker", e);
    }
    throw e;
}

Prevention

Set transactionCoordinatorEnabled=true in broker.conf wherever transactions are used.
Keep broker configs consistent across the cluster to avoid hitting non-transactional brokers.
Verify via GET /admin/v2/brokers/configuration before calling transaction endpoints.
Enable transaction-related config for k8s via PULSAR_PREFIX_ environment variables.

When it happens

Trigger: Calling any TransactionsBase admin endpoint (e.g. /admin/v3/transaction/coordinatorScaleCoordinator/{replicas}, coordinator stats) on a broker where transactionCoordinatorEnabled is false (the default).

Common situations: Enabling transactions only on clients but forgetting broker config; hitting the wrong broker in a mixed cluster where only some brokers enable transactions; upgrading an environment and transactions config not carried over.

Related errors

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