{"record":{"id":"97a898921b36ba42","repo":"apache/pulsar","slug":"invalid-config-socks5proxy-address","errorCode":null,"errorMessage":"Invalid config [socks5Proxy.address]","messagePattern":"Invalid config \\[socks5Proxy\\.address\\]","errorType":"validation","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"pulsar-client/src/main/java/org/apache/pulsar/client/impl/conf/ClientConfigurationData.java","lineNumber":620,"sourceCode":"    public ClientConfigurationData clone() {\n        try {\n            return (ClientConfigurationData) super.clone();\n        } catch (CloneNotSupportedException e) {\n            throw new RuntimeException(\"Failed to clone ClientConfigurationData\");\n        }\n    }\n\n    public InetSocketAddress getSocks5ProxyAddress() {\n        if (Objects.nonNull(socks5ProxyAddress)) {\n            return socks5ProxyAddress;\n        }\n        String proxyAddress = System.getProperty(\"socks5Proxy.address\");\n        return Optional.ofNullable(proxyAddress).map(address -> {\n            try {\n                URI uri = URI.create(address);\n                return new InetSocketAddress(uri.getHost(), uri.getPort());\n            } catch (Exception e) {\n                throw new RuntimeException(\"Invalid config [socks5Proxy.address]\", e);\n            }\n        }).orElse(null);\n    }\n\n    public String getSocks5ProxyUsername() {\n        return Objects.nonNull(socks5ProxyUsername) ? socks5ProxyUsername : System.getProperty(\"socks5Proxy.username\");\n    }\n\n    public String getSocks5ProxyPassword() {\n        return Objects.nonNull(socks5ProxyPassword) ? socks5ProxyPassword : System.getProperty(\"socks5Proxy.password\");\n    }\n\n    public void setLookupProperties(Map<String, String> lookupProperties) {\n        this.lookupProperties = Collections.unmodifiableMap(lookupProperties);\n    }\n\n    public Map<String, String> getLookupProperties() {\n        return (lookupProperties == null) ? Collections.emptyMap() : Collections.unmodifiableMap(lookupProperties);","sourceCodeStart":602,"sourceCodeEnd":638,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client/src/main/java/org/apache/pulsar/client/impl/conf/ClientConfigurationData.java#L602-L638","documentation":"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]\".","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a fully-qualified URI form including the port: -Dsocks5Proxy.address=socks5://proxy.host:1080.","If the host is unresolvable, fix DNS or use an IP address; bracket IPv6 literals (socks5://[::1]:1080).","Alternatively set socks5ProxyAddress in ClientConfigurationData programmatically instead of the system property.","Validate the property value with URI.create + getHost()/getPort() in a smoke test before deployment."],"exampleFix":"// before\n-Dsocks5Proxy.address=proxy.corp:1080\n// after\n-Dsocks5Proxy.address=socks5://proxy.corp:1080","handlingStrategy":"validation","validationCode":"String addr = System.getProperty(\"socks5Proxy.address\");\nif (addr != null) {\n    java.net.URI u = java.net.URI.create(addr);\n    if (u.getHost() == null || u.getPort() <= 0 || u.getPort() > 65535) {\n        throw new IllegalStateException(\"socks5Proxy.address must be scheme://host:port, got: \" + addr);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    InetSocketAddress sa = conf.getSocks5ProxyAddress();\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Invalid config [socks5Proxy.address]\")) {\n        // fix the property or clear it\n    } else throw e;\n}","preventionTips":["Always include scheme, host, and port: socks5://host:port (port is mandatory).","Bracket IPv6 literals and avoid spaces/quotes in the JVM argument.","Prefer setting socks5ProxyAddress programmatically over system properties to catch errors at startup."],"tags":["socks5-proxy","configuration","system-property","uri-parse"],"backgroundTag":"invalid-proxy-address-config","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}