apache/pulsar · error · IllegalArgumentException

The broker ${brokerAddress} is not among the assigned broker

Error message

The broker ${brokerAddress} is not among the assigned broker pools for the controlled namespace.

What it means

NamespaceIsolationPolicies.getBrokerAssignment() classifies a broker as primary or secondary for a namespace whose namespace-isolation policy is defined. If the broker matches neither the policy's primary nor secondary broker regex lists, the broker is outside all assigned pools and the method throws IllegalArgumentException. This is a policy-configuration inconsistency, not a runtime failure of the broker.

Source

Thrown at pulsar-common/src/main/java/org/apache/pulsar/common/policies/impl/NamespaceIsolationPolicies.java:148

    }

    /**
     * Get the broker assignment based on the namespace name.
     *
     * @param nsPolicy
     *            The namespace name
     * @param brokerAddress
     *            The broker address is the format of host:port
     * @return The broker assignment: {primary, secondary, shared}
     */
    private BrokerAssignment getBrokerAssignment(NamespaceIsolationPolicy nsPolicy, String brokerAddress) {
        if (nsPolicy != null) {
            if (nsPolicy.isPrimaryBroker(brokerAddress)) {
                return BrokerAssignment.primary;
            } else if (nsPolicy.isSecondaryBroker(brokerAddress)) {
                return BrokerAssignment.secondary;
            }
            throw new IllegalArgumentException("The broker " + brokerAddress
                    + " is not among the assigned broker pools for the controlled namespace.");
        }
        // Only uncontrolled namespace will be assigned to the shared pool
        if (!this.isSharedBroker(brokerAddress)) {
            throw new IllegalArgumentException("The broker " + brokerAddress
                    + " is not among the shared broker pools for the uncontrolled namespace.");
        }
        return BrokerAssignment.shared;
    }

    public void assignBroker(NamespaceName nsname, BrokerStatus brkStatus, SortedSet<BrokerStatus> primaryCandidates,
            SortedSet<BrokerStatus> secondaryCandidates, SortedSet<BrokerStatus> sharedCandidates) {
        NamespaceIsolationPolicy nsPolicy = this.getPolicyByNamespace(nsname);
        BrokerAssignment brokerAssignment = this.getBrokerAssignment(nsPolicy, brkStatus.getBrokerAddress());
        if (brokerAssignment == BrokerAssignment.primary) {
            // Only add to candidates if allowed by policy
            if (nsPolicy != null && nsPolicy.isPrimaryBrokerAvailable(brkStatus)) {
                primaryCandidates.add(brkStatus);

View on GitHub (pinned to 820761864e)

Solutions

1. Add the broker's service URL pattern to the policy's primary or secondary broker regex list in namespaceIsolationPolicies.json
2. Fix the broker's advertised service URL so it matches an existing regex (e.g. consistent FQDN)
3. Verify regexes with a quick test against the actual broker URL before deploying
4. Remove/recreate the isolation policy if the namespace should be uncontrolled

Example fix

// before (policy)
"primary": ["broker-1.*.cluster"]   // broker URL is broker-5.us-west.example.com:6650 — no match
// after
"primary": ["broker-[0-9]+\\.us-west\\.example\\.com.*"],
"secondary": ["broker-[0-9]+\\.us-east\\.example\\.com.*"]

// Check the broker matches primary or secondary regexes before classification
boolean matches = policy != null &&
    (policy.isPrimaryBroker(brokerUrl) || policy.isSecondaryBroker(brokerUrl));
if (!matches) throw new IllegalStateException("Broker " + brokerUrl + " not in isolation policy pools");

static boolean brokerInPolicy(NamespaceIsolationPolicyImpl p, String url) {
    return p != null && (p.isPrimaryBroker(url) || p.isSecondaryBroker(url));
}

try {
    BrokerAssignment a = policies.brokerAssignment(ns, brokerUrl);
} catch (IllegalArgumentException e) {
    log.warn("Broker {} not covered by isolation policy for {}: {}", brokerUrl, ns, e.getMessage());
    // treat as unassigned / alert, don't crash the selection loop
}

When it happens

Trigger: Calling brokerAssignment (or getBrokerAssignment) with a brokerAddress whose service URL matches no primary/secondary regex in the namespace's isolation policy, while a policy exists for that namespace (controlled namespace).

Common situations: A broker started with a service URL that doesn't match any configured regex (hostname vs FQDN vs IP mismatch), typo in the regex, or a new broker added without updating the isolation policy.

Related errors

• The broker ${brokerAddress} is not among the shared broker p
• Namespace ${namespace} does not match policy
• Timeout during mark-delete operation
• Timeout during clear backlog operation
• Timeout during skip messages operation

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