apache/pulsar · error · IllegalArgumentException

listener name `${name}` must contain only ASCII letters, dig

Error message

listener name `${name}` must contain only ASCII letters, digits, underscore, or hyphen

What it means

IllegalArgumentException thrown by MultipleListenerValidator.validateListenerName when the listener name contains characters outside ASCII letters, digits, underscore, and hyphen (LISTENER_NAME_PATTERN). Names must be safe to embed in URLs without percent-encoding, so characters like spaces, dots, colons, or non-ASCII letters are rejected.

Source

Thrown at pulsar-broker-common/src/main/java/org/apache/pulsar/broker/validator/MultipleListenerValidator.java:73

                ? host.substring(1, host.length() - 1) : host;
        if (NetUtil.isValidIpV6Address(unbracketed)) {
            return "[" + unbracketed + "]:" + uri.getPort();
        }
        return host + ":" + uri.getPort();
    }

    /**
     * Validate a listener name. Listener names must be non-blank and contain only ASCII letters,
     * digits, underscore, and hyphen so they are safe to embed in URLs without encoding.
     *
     * @throws IllegalArgumentException if the name is null, blank, or contains disallowed characters.
     */
    public static void validateListenerName(String name) {
        if (StringUtils.isBlank(name)) {
            throw new IllegalArgumentException("listener name must not be blank");
        }
        if (!LISTENER_NAME_PATTERN.matcher(name).matches()) {
            throw new IllegalArgumentException("listener name `" + name + "` must contain only ASCII"
                    + " letters, digits, underscore, or hyphen");
        }
    }

    /**
     * Validate `advertisedListeners` and `internalListenerName`, returning the parsed listener map.
     * <p>
     * This method mutates the supplied {@link ServiceConfiguration}: when {@code internalListenerName}
     * is blank, it is written back with the resolved fallback value (the first parsed listener if any,
     * otherwise {@value ServiceConfiguration#DEFAULT_INTERNAL_LISTENER_NAME}) so that subsequent reads
     * from the config see the effective value.
     * <ol>
     * <li>`advertisedListeners` is a comma-separated list of endpoints in the form
     *     `listener:scheme://host:port`. Supported schemes are `pulsar`, `pulsar+ssl`, `http`, and `https`.
     * <li>A listener name may be repeated to define multiple endpoints (e.g. binary and HTTPS) for the
     *     same listener; duplicate definitions for the same scheme are rejected.
     * <li>`internalListenerName` identifies the listener used for cluster-internal broker-to-broker
     *     communication. It defaults to {@value ServiceConfiguration#DEFAULT_INTERNAL_LISTENER_NAME}.

View on GitHub (pinned to 820761864e)

Solutions

1. Rename the listener using only [A-Za-z0-9_-], e.g. tls_internal or pulsar-tls
2. Update internalListenerName to match the renamed listener everywhere it is referenced
3. Keep listener names distinct from hostnames to avoid dot temptation

Example fix

// before
advertisedListeners=tls.internal:pulsar+ssl://host:6651
// after
advertisedListeners=tls-internal:pulsar+ssl://host:6651

if (!name.matches("[A-Za-z0-9_-]+")) {
    throw new IllegalArgumentException("listener name '" + name + "' must contain only ASCII letters, digits, underscore, or hyphen");
}

static boolean isValidListenerName(String name) {
    return name != null && name.matches("[A-Za-z0-9_-]+");
}

When it happens

Trigger: Configuring advertisedListeners or internalListenerName with names such as "my listener", "pulsar.tls", "broker#1", or Unicode names; validateBindAddresses also calls this on the name group of each bindAddresses entry.

Common situations: Using DNS-style dots in listener names (e.g. tls.internal); copying a hostname including dots as the listener name; localized/Unicode names from templating systems.

Related errors

• listener name must not be blank
• the configure entry `advertisedListeners` is invalid. becaus
• Timeout during delete operation
• Timeout during close operation
• Timeout during open-cursor operation

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