apache/pulsar · error · RuntimeException

Invalid config [socks5Proxy.address]

Error message

Invalid config [socks5Proxy.address]

What it means

getSocks5ProxyAddress resolves the SOCKS5 proxy from the socks5Proxy.address system property (when the field is not set). It parses the property as a URI and builds an InetSocketAddress; any parse/resolution error (malformed URI, bad port, unresolvable host) is wrapped in a RuntimeException "Invalid config [socks5Proxy.address]".

Source

Thrown at pulsar-client/src/main/java/org/apache/pulsar/client/impl/conf/ClientConfigurationData.java:620

    public ClientConfigurationData clone() {
        try {
            return (ClientConfigurationData) super.clone();
        } catch (CloneNotSupportedException e) {
            throw new RuntimeException("Failed to clone ClientConfigurationData");
        }
    }

    public InetSocketAddress getSocks5ProxyAddress() {
        if (Objects.nonNull(socks5ProxyAddress)) {
            return socks5ProxyAddress;
        }
        String proxyAddress = System.getProperty("socks5Proxy.address");
        return Optional.ofNullable(proxyAddress).map(address -> {
            try {
                URI uri = URI.create(address);
                return new InetSocketAddress(uri.getHost(), uri.getPort());
            } catch (Exception e) {
                throw new RuntimeException("Invalid config [socks5Proxy.address]", e);
            }
        }).orElse(null);
    }

    public String getSocks5ProxyUsername() {
        return Objects.nonNull(socks5ProxyUsername) ? socks5ProxyUsername : System.getProperty("socks5Proxy.username");
    }

    public String getSocks5ProxyPassword() {
        return Objects.nonNull(socks5ProxyPassword) ? socks5ProxyPassword : System.getProperty("socks5Proxy.password");
    }

    public void setLookupProperties(Map<String, String> lookupProperties) {
        this.lookupProperties = Collections.unmodifiableMap(lookupProperties);
    }

    public Map<String, String> getLookupProperties() {
        return (lookupProperties == null) ? Collections.emptyMap() : Collections.unmodifiableMap(lookupProperties);

View on GitHub (pinned to 820761864e)

Solutions

1. Use a fully-qualified URI form including the port: -Dsocks5Proxy.address=socks5://proxy.host:1080.
2. If the host is unresolvable, fix DNS or use an IP address; bracket IPv6 literals (socks5://[::1]:1080).
3. Alternatively set socks5ProxyAddress in ClientConfigurationData programmatically instead of the system property.
4. Validate the property value with URI.create + getHost()/getPort() in a smoke test before deployment.

Example fix

// before
-Dsocks5Proxy.address=proxy.corp:1080
// after
-Dsocks5Proxy.address=socks5://proxy.corp:1080

String addr = System.getProperty("socks5Proxy.address");
if (addr != null) {
    java.net.URI u = java.net.URI.create(addr);
    if (u.getHost() == null || u.getPort() <= 0 || u.getPort() > 65535) {
        throw new IllegalStateException("socks5Proxy.address must be scheme://host:port, got: " + addr);
    }
}

try {
    InetSocketAddress sa = conf.getSocks5ProxyAddress();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Invalid config [socks5Proxy.address]")) {
        // fix the property or clear it
    } else throw e;
}

When it happens

Trigger: Starting the client with -Dsocks5Proxy.address set to a malformed value — missing port, non-numeric port, invalid characters, or a URI scheme/host the parser cannot handle; caught during connection setup via PulsarChannelInitializer / socks5Address.

Common situations: Ops misconfiguration like "proxy.corp:1080" without a scheme (URI.create can yield unexpected host/port) or "socks5://host" without a port; whitespace or quoted values in JVM args; IPv6 literals needing brackets.

Related errors

• Property
• Timeout during mark-delete operation
• Timeout during clear backlog operation
• Timeout during skip messages operation
• Timeout during delete operation

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