apache/pulsar · error · IllegalArgumentException

Illegal broker host:port '${brokerPortAndHost}'

Error message

Illegal broker host:port '${brokerPortAndHost}'

What it means

parseHost splits a 'host:port' broker string at the last colon; if there is no colon it cannot extract a host and throws IllegalArgumentException. It is called from DirectProxyHandler.connect when the proxy opens a direct connection to the target broker.

Source

Thrown at pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/DirectProxyHandler.java:195

                        .attr("targetAddress", targetBrokerAddress)
                        .attr("brokerHost", brokerHostAndPort)
                        .exception(future.cause())
                        .log("Establishing connection failed. Closing inbound channel.");
                Channel channel = f.channel();
                if (channel != null) {
                    channel.close();
                }
                inboundChannel.close();
            }
        });
    }

    private static String parseHost(String brokerPortAndHost) {
        int pos = brokerPortAndHost.lastIndexOf(':');
        if (pos > 0) {
            return brokerPortAndHost.substring(0, pos);
        } else {
            throw new IllegalArgumentException("Illegal broker host:port '" + brokerPortAndHost + "'");
        }
    }

    private void writeHAProxyMessage() {
        if (proxyConnection.hasHAProxyMessage()) {
            final ByteBuf msg = encodeProxyProtocolMessage(proxyConnection.getHAProxyMessage());
            writeAndFlush(msg);
        } else {
            if (inboundChannel.remoteAddress() instanceof InetSocketAddress
                    && inboundChannel.localAddress() instanceof InetSocketAddress) {
                InetSocketAddress clientAddress = (InetSocketAddress) inboundChannel.remoteAddress();
                String sourceAddress = clientAddress.getAddress().getHostAddress();
                int sourcePort = clientAddress.getPort();
                InetSocketAddress proxyAddress = (InetSocketAddress) inboundChannel.localAddress();
                String destinationAddress = proxyAddress.getAddress().getHostAddress();
                int destinationPort = proxyAddress.getPort();
                HAProxyMessage msg = new HAProxyMessage(HAProxyProtocolVersion.V1, HAProxyCommand.PROXY,
                        HAProxyProxiedProtocol.TCP4, sourceAddress, destinationAddress, sourcePort,

View on GitHub (pinned to 820761864e)

Solutions

  1. Ensure the broker target string always includes a port, e.g. '10.0.0.1:6650'
  2. Fix brokerServiceURL / discovery configuration so it returns full host:port values
  3. Log the incoming brokerPortAndHost at the call site to find which component produced the malformed value
  4. For IPv6 hosts, ensure bracketed literals like '[::1]:6650' so lastIndexOf(':') finds the port separator

Example fix

// before
brokerServiceURL=pulsar://broker-1
// after
brokerServiceURL=pulsar://broker-1:6650
Defensive patterns

Strategy: validation

Validate before calling

// Guard before passing a broker string to the direct proxy handler
static boolean isHostPort(String s) {
    return s != null && s.lastIndexOf(':') > 0 && s.lastIndexOf(':') < s.length() - 1;
}

Type guard

boolean isHostPort(String s) {
    int pos = s == null ? -1 : s.lastIndexOf(':');
    return pos > 0 && pos < s.length() - 1;
}

Try / catch

try { handler.connect(brokerPortAndHost, ...); } catch (IllegalArgumentException e) { log.error("Broker target must be host:port, got: {}", brokerPortAndHost); throw e; }

Prevention

When it happens

Trigger: connect(brokerPortAndHost, ...) receiving a string without a ':' separator — e.g. a bare hostname, an empty value, or a broker service URL missing its port component.

Common situations: Misconfigured brokerServiceURL without the port; a lookup result altered by a custom discovery layer; trimming the ':6650' when copying config between environments; IPv6 literal handled without brackets in surrounding code.

Related errors

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