apache/pulsar · error · RestException

RestException(e.getCause())

Error message

RestException(e.getCause())

What it means

getTopicReference waits for getTopicIfExists(...) future and, when the future completes exceptionally, wraps the underlying cause in a RestException. The message string shown is the generic wrapping, but the actual HTTP response reflects the cause (e.g. topic load failure, broker service error). It indicates the topic lookup failed on the broker while serving a non-persistent topic admin read (e.g. GET topic stats/permissions).

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/NonPersistentTopics.java:705

                            .attr("namespace", namespace)
                            .attr("topic", topicName.getLocalName())
                            .attr("isGlobal", isGlobal)
                            .log("Successfully remove entry filters");
                    asyncResponse.resume(Response.noContent().build());
                })
                .exceptionally(ex -> {
                    handleTopicPolicyException("removeEntryFilters", ex, asyncResponse);
                    return null;
                });
    }

    private Topic getTopicReference(TopicName topicName) {
        try {
            return pulsar().getBrokerService().getTopicIfExists(topicName.toString())
                    .get(config().getMetadataStoreOperationTimeoutSeconds(), TimeUnit.SECONDS)
                    .orElseThrow(() -> new RestException(Status.NOT_FOUND, "Topic not found"));
        } catch (ExecutionException e) {
            throw new RestException(e.getCause());
        } catch (InterruptedException | TimeoutException e) {
            throw new RestException(e);
        }
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Inspect the cause field of the returned RestException / the broker log for the real underlying error
2. Verify metadata store connectivity and health of the broker serving the request
3. Retry the admin call once the broker/metadata store is healthy

// pre-check: confirm topic exists and broker is healthy
admin.topics().getList(namespace).contains(topicName);

try { t = admin.topics().stats(topic); } catch (PulsarAdminException e) { log.error("topic lookup failed: {}", e.getCause()); }

When it happens

Trigger: Any admin call that resolves to getTopicReference when BrokerService.getTopicIfExists completes exceptionally — e.g. metadata store errors, topic load failures — within metadataStoreOperationTimeoutSeconds.

Common situations: Metadata store (ZooKeeper/etcd) connectivity problems, topic being concurrently deleted, broker service exceptions during topic creation/load.

Related errors

• RestException(e)
• This Broker is not configured with transactionCoordinatorEna
• Cannot start the service once it was stopped
• webServicePort/webServicePortTls or http/https bindAddresses
• The retention size must > the backlog quota limit size, but

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