apache/pulsar · error · IllegalArgumentException

Invalid IP address filter

Error message

Invalid IP address filter '${ipAddressString}'

What it means

BrokerProxyValidator parses the proxy's allowed IP address filters into IPAddressString objects; any entry that is not a syntactically valid IP address or CIDR throws IllegalArgumentException immediately at validator construction. The message includes the offending filter string and the underlying address parse exception.

Solutions

1. Fix the offending filter string shown in the message to a valid IP or CIDR (e.g. 10.0.0.0/24, 2001:db8::/32)
2. Remove any hostname entries — the filter accepts IP addresses/subnets, not DNS names
3. Validate each entry with an IP/CIDR calculator before adding it to the config
4. Restart the proxy and confirm the validator initializes without error

Example fix

// before
brokerProxyAllowedIPAddresses=10.0.0.0/24,mybroker.example.com
// after
brokerProxyAllowedIPAddresses=10.0.0.0/24,192.168.1.5

// Validate every filter entry before writing proxy config
for (String s : allowedIpStrings.split(",")) {
    IPAddressString ips = new IPAddressString(s.trim());
    if (!ips.isValid()) throw new IllegalArgumentException("Bad IP filter: " + s + " -> " + ips.getAddressStringException());
}

boolean isValidIpFilter(String s) {
    IPAddressString ips = new IPAddressString(s.trim());
    return ips.isValid() && ips.getAddress() != null;
}

try { new BrokerProxyValidator(conf); } catch (IllegalArgumentException e) { log.error("Fix IP filter config: {}", e.getMessage()); throw e; }

When it happens

Trigger: Constructing BrokerProxyValidator with configuration containing an invalid entry in the IP allow list (e.g. proxyilaterally 'brokerProxyAllowedIPAddresses' style settings): typos, hostnames instead of IPs, malformed CIDR like '10.0.0.0/33'.

Common situations: Putting hostnames in an IP filter list; CIDR with an out-of-range prefix; stray whitespace or characters; IPv6 notation errors; copy-paste with comma/semicolon confusion.

Related errors

• httpReverseProxy. .path must be specified exactly once
• httpReverseProxy. .proxyTo must be specified exactly once
• Allowed offset for athenz role token verification must not…
• Cannot add servlet at
• checkHealthyIntervalMs must be larger than 0

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

Appendix: source

Thrown at pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/BrokerProxyValidator.java:74

            this.allowAnyHostName = true;
            this.allowedHostNames = Collections.emptyList();
        } else {
            this.allowAnyHostName = false;
            this.allowedHostNames = allowedHostNamesStrings.stream()
                    .map(BrokerProxyValidator::parseWildcardPattern).collect(Collectors.toList());
        }
        List<String> allowedIPAddressesStrings = parseCommaSeparatedConfigValue(allowedIPAddresses);
        if (allowedIPAddressesStrings.contains(ALLOW_ANY)) {
            allowAnyIPAddress = true;
            this.allowedIPAddresses = Collections.emptyList();
        } else {
            allowAnyIPAddress = false;
            this.allowedIPAddresses = allowedIPAddressesStrings.stream().map(IPAddressString::new)
                    .filter(ipAddressString -> {
                        if (ipAddressString.isValid()) {
                            return true;
                        } else {
                            throw new IllegalArgumentException("Invalid IP address filter '" + ipAddressString + "'",
                                    ipAddressString.getAddressStringException());
                        }
                    }).map(IPAddressString::getAddress)
                    .filter(Objects::nonNull)
                    .collect(Collectors.toList());
        }
        List<String> allowedTargetPortsStrings = parseCommaSeparatedConfigValue(allowedTargetPorts);
        if (allowedTargetPortsStrings.contains(ALLOW_ANY)) {
            allowAnyTargetPort = true;
            this.allowedTargetPorts = new int[0];
        } else {
            allowAnyTargetPort = false;
            this.allowedTargetPorts =
                    allowedTargetPortsStrings.stream().mapToInt(Integer::parseInt).toArray();
        }
    }

    private static Pattern parseWildcardPattern(String wildcardPattern) {

View on GitHub (pinned to 820761864e)