apache/pulsar · error · IllegalArgumentException

httpReverseProxy.%s.path must be specified exactly once

Error message

httpReverseProxy.%s.path must be specified exactly once

What it means

During ProxyConfiguration validation, httpReverseProxy properties are grouped by their logical name; each group must contain exactly one 'path' (and 'proxyTo') key. If a named reverse-proxy group lacks a 'path' property the configuration is rejected with this IllegalArgumentException.

Source

Thrown at pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/ProxyConfiguration.java:1116

    public Optional<Integer> getWebServicePortTls() {
        return webServicePortTls;
    }

    public void setProperties(Properties properties) {
        this.properties = properties;

        Map<String, Map<String, String>> redirects = new HashMap<>();
        Pattern redirectPattern = Pattern.compile("^httpReverseProxy\\.([^\\.]*)\\.(.+)$");
        Map<String, List<Matcher>> groups = properties.stringPropertyNames().stream()
            .map((s) -> redirectPattern.matcher(s))
            .filter(Matcher::matches)
            .collect(Collectors.groupingBy((m) -> m.group(1))); // group by name

        groups.entrySet().forEach((e) -> {
                Map<String, String> keyToFullKey = e.getValue().stream().collect(
                        Collectors.toMap(m -> m.group(2), m -> m.group(0)));
                if (!keyToFullKey.containsKey("path")) {
                    throw new IllegalArgumentException(
                            String.format("httpReverseProxy.%s.path must be specified exactly once", e.getKey()));
                }
                if (!keyToFullKey.containsKey("proxyTo")) {
                    throw new IllegalArgumentException(
                            String.format("httpReverseProxy.%s.proxyTo must be specified exactly once", e.getKey()));
                }
                httpReverseProxyConfigs.add(new HttpReverseProxyConfig(e.getKey(),
                                                    properties.getProperty(keyToFullKey.get("path")),
                                                    properties.getProperty(keyToFullKey.get("proxyTo"))));
            });
    }

    public static class HttpReverseProxyConfig {
        private final String name;
        private final String path;
        private final String proxyTo;

        HttpReverseProxyConfig(String name, String path, String proxyTo) {

View on GitHub (pinned to 820761864e)

Solutions

  1. Add the missing httpReverseProxy.<name>.path property for the group named in the message
  2. Also confirm httpReverseProxy.<name>.proxyTo is present, or the sibling error will fire next
  3. Check for group-name typos that split one logical proxy into two partial groups
  4. Restart the proxy and verify the reverse proxy route registers

Example fix

// before
httpReverseProxy.myapp.proxyTo=http://localhost:8080
// after
httpReverseProxy.myapp.path=/myapp
httpReverseProxy.myapp.proxyTo=http://localhost:8080
Defensive patterns

Strategy: validation

Validate before calling

// Pre-validate reverse proxy config groups
Map<String, Set<String>> groups = groupHttpReverseProxyKeys(properties);
for (var e : groups.entrySet()) {
    if (!e.getValue().contains("path")) throw new IllegalStateException("httpReverseProxy." + e.getKey() + ".path must be specified exactly once");
    if (!e.getValue().contains("proxyTo")) throw new IllegalStateException("httpReverseProxy." + e.getKey() + ".proxyTo must be specified exactly once");
}

Try / catch

try { conf.validate(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("httpReverseProxy")) log.error("Incomplete reverse-proxy group: {}", e.getMessage()); throw e; }

Prevention

When it happens

Trigger: Proxy startup with properties like httpReverseProxy.myapp.proxyTo set but no corresponding httpReverseProxy.myapp.path — the regex-based grouping finds the group but the required key is missing.

Common situations: Copy-pasting a reverse-proxy config block and deleting the path line; renaming the group in one line but not the other so a group is left with only proxyTo; typos like 'paths' or 'Path'.

Related errors

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