apache/pulsar · error · RestException

Subscription has active connected consumers

Error message

Subscription has active connected consumers

What it means

Thrown when deleting a subscription from a namespace via the admin API: the broker attempted the deletion but a SubscriptionBusyException occurred because consumers are still actively connected to that subscription. It is translated to HTTP 412 PRECONDITION_FAILED, telling the caller the subscription cannot be removed while in use.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/NamespacesBase.java:2372

                                    if (optTopic.isEmpty()) {
                                        return CompletableFuture.completedFuture(null);
                                    }
                                    Topic loaded = optTopic.get();
                                    Subscription sub = loaded.getSubscription(subscription);
                                    if (sub == null) {
                                        return CompletableFuture.completedFuture(null);
                                    }
                                    return sub.delete();
                                }));
                    }
                    return FutureUtil.waitForAll(futures);
                }).exceptionally(ex -> {
                    Throwable cause = FutureUtil.unwrapCompletionException(ex);
                    if (cause instanceof RestException) {
                        throw (RestException) cause;
                    }
                    if (cause instanceof SubscriptionBusyException) {
                        throw new RestException(Status.PRECONDITION_FAILED,
                                "Subscription has active connected consumers");
                    }
                    throw new RestException(cause);
                });
    }

    protected BundlesData validateBundlesData(BundlesData initialBundles) {
        SortedSet<String> partitions = new TreeSet<String>();
        for (String partition : initialBundles.getBoundaries()) {
            Long partBoundary = Long.decode(partition);
            partitions.add(String.format("0x%08x", partBoundary));
        }
        if (partitions.size() != initialBundles.getBoundaries().size()) {
                log.debug("Input bundles included repeated partition points. Ignored.");
                    }
        try {
            NamespaceBundleFactory.validateFullRange(partitions);
        } catch (IllegalArgumentException iae) {

View on GitHub (pinned to 820761864e)

Solutions

  1. Close all consumers/readers using the subscription, then retry the deletion
  2. Pass force=true to the delete call to disconnect consumers and force-delete (use with care: in-flight messages may be lost)
  3. Identify connected consumers via GET /persistent/{tenant}/{ns}/{topic}/subscriptions/{sub}/... stats and shut them down
  4. Wait for consumer clients to reconnect/disconnect (e.g. after a rolling restart) before retrying

Example fix

// before
admin.namespaces().deleteSubscription("my-tenant/my-ns", "my-sub"); // 412 if consumers connected
// after
consumer.close(); // close all consumers of 'my-sub' first
admin.namespaces().deleteSubscription("my-tenant/my-ns", "my-sub");
// or force:
admin.namespaces().deleteSubscription("my-tenant/my-ns", "my-sub", true);
Defensive patterns

Strategy: try-catch

Validate before calling

PersistentTopicInternalStats stats = null;
// prefer checking consumers before delete:
// if any consumer entries exist under the subscription, close them first
boolean hasConsumers = topicStats != null && topicStats.subscriptions
    .getOrDefault(sub, new SubscriptionStats()).consumers.size() > 0;
if (hasConsumers) throw new IllegalStateException("Close consumers of " + sub + " before deletion");

Try / catch

try {
    admin.namespaces().deleteSubscription(ns, sub);
} catch (PulsarAdminException.PreconditionFailedException e) {
    // consumers still connected: either close them or force-delete
    admin.namespaces().deleteSubscription(ns, sub, true);
}

Prevention

When it happens

Trigger: DELETE /namespaces/{ns}/subscription/{sub} (or namespace-level unsubscribe of a persistent subscription) while live consumers with that subscription name are connected; failing to close/drain all readers/consumers (including shared/exclusive consumers in other clients) before deletion.

Common situations: CI teardown scripts that don't close consumers before cleaning namespaces; streaming apps with redundant consumer instances still running; lingering readers (cursor-based) attached to the subscription; force flag omitted while consumers are active.

Related errors

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