apache/pulsar · error · RestException

Namespace does not exist

Error message

Namespace does not exist

What it means

HTTP 404 returned by the subscription-level permission grant API (POST /namespaces/{tenant}/{namespace}/permissions/subscription/{role}) when the underlying cause chain ends in IllegalArgumentException. The IllegalArgumentException was historically thrown by grantPermissionAsync for a missing namespace, so it is mapped to 'Namespace does not exist' for backward compatibility.

Source

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

                })
                .thenCompose(__ -> getAuthorizationService()
                        .grantSubscriptionPermissionAsync(namespaceName, subscription, roles, null))
                .thenAccept(unused -> {
                    log.info()
                            .attr("role", roles)
                            .attr("subscription", subscription)
                            .attr("namespace", namespaceName)
                            .log("Successfully granted permission on subscription for role: - namespaceName");
                })
                .exceptionally(ex -> {
                    Throwable realCause = FutureUtil.unwrapCompletionException(ex);
                    //The IllegalArgumentException and the IllegalStateException were historically thrown by the
                    // grantPermissionAsync method, so we catch them here to ensure backwards compatibility.
                    if (realCause.getCause() instanceof IllegalArgumentException) {
                        log.warn()
                                .attr("namespace", namespaceName)
                                .log("Failed to set permissions for namespace : does not exist");
                        throw new RestException(Status.NOT_FOUND, "Namespace does not exist");
                    } else if (realCause.getCause() instanceof IllegalStateException) {
                        log.warn()
                                .attr("namespace", namespaceName)
                                .log("Failed to set permissions for namespace : concurrent modification");
                        throw new RestException(Status.CONFLICT, "Concurrent modification");
                    } else {
                        log.error()
                                .attr("namespace", namespaceName)
                                .exceptionMessage(realCause)
                                .log("Failed to get permissions for namespace");
                        throw new RestException(realCause);
                    }
                });
    }

    protected CompletableFuture<Void> internalRevokePermissionsOnNamespaceAsync(String role) {
        return validateNamespaceOperationAsync(namespaceName, NamespaceOperation.REVOKE_PERMISSION)
                .thenAccept(__ -> checkNotNull(role, "Role should not be null"))

View on GitHub (pinned to 820761864e)

Solutions

  1. Verify the namespace exists via GET /namespaces/{tenant}/{namespace} before granting.
  2. Correct the namespace name in the admin call.
  3. Recreate the namespace if deletion was unintended, then retry the grant.
  4. If you own an old client relying on IllegalArgumentException, migrate to checking the HTTP 404 response instead.

Example fix

// before
admin.namespaces().grantPermissionOnSubscription(ns, sub, role, actions); // 404
// after
if (admin.namespaces().getNamespaces(tenant).contains(ns)) {
    admin.namespaces().grantPermissionOnSubscription(ns, sub, role, actions);
}
Defensive patterns

Strategy: validation

Validate before calling

boolean exists = admin.namespaces().getNamespaces(tenant)
        .contains(tenant + "/" + namespace);
if (!exists) throw new IllegalStateException("Namespace does not exist: " + namespace);

Try / catch

try {
    admin.namespaces().grantPermissionOnSubscription(ns, sub, role, actions);
} catch (PulsarAdminException.NotFoundException e) {
    // namespace missing: create it or abort
}

Prevention

When it happens

Trigger: Granting subscription permissions on a namespace that does not exist, has been deleted, or whose name is invalid, with the failure arriving as a wrapped IllegalArgumentException inside the CompletionException cause chain.

Common situations: ACL setup scripts referencing a namespace removed earlier; wrong tenant/namespace in automation config; calling subscription-grant during namespace creation teardown race.

Related errors

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