alibaba/nacos · error · IllegalArgumentException

Illegal url path expression : {subPath}

Error message

Illegal url path expression : {subPath}

What it means

Thrown by HttpUtils.buildUrl() as an IllegalArgumentException when any individual subPath segment contains two or more consecutive forward slashes, matched by the regex (\/)\1+. This is the same pattern used by ValidatorUtils.checkContextPath (error 722) but applied to URL path segments during URL construction. Blank subPaths are skipped, but any non-blank subPath with '//' is rejected. The message includes the offending subPath.

Source

Thrown at common/src/main/java/com/alibaba/nacos/common/http/HttpUtils.java:159

     * @param subPaths   api path
     * @return URL string
     */
    public static String buildUrl(boolean isHttps, String serverAddr, String... subPaths) {
        StringBuilder sb = new StringBuilder();
        if (isHttps) {
            sb.append(HTTPS_PREFIX);
        } else {
            sb.append(HTTP_PREFIX);
        }
        sb.append(serverAddr);
        String pre = null;
        for (String subPath : subPaths) {
            if (StringUtils.isBlank(subPath)) {
                continue;
            }
            Matcher matcher = CONTEXT_PATH_MATCH.matcher(subPath);
            if (matcher.find()) {
                throw new IllegalArgumentException("Illegal url path expression : " + subPath);
            }
            if (pre == null || !pre.endsWith("/")) {
                if (subPath.startsWith("/")) {
                    sb.append(subPath);
                } else {
                    sb.append('/').append(subPath);
                }
            } else {
                if (subPath.startsWith("/")) {
                    sb.append(subPath.replaceFirst("\\/", ""));
                } else {
                    sb.append(subPath);
                }
            }
            pre = subPath;
        }
        return sb.toString();
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Normalize each subPath segment to remove consecutive slashes before passing to buildUrl.
2. Ensure context path segments do not have trailing slashes when the next segment has a leading slash.
3. Use a URL-building utility that handles slash joining automatically.

Example fix

// before
String url = HttpUtils.buildUrl(false, "127.0.0.1:8848", "/nacos//v3", "/config");

// after — normalize each segment
String url = HttpUtils.buildUrl(false, "127.0.0.1:8848", "/nacos/v3", "/config");

for (String subPath : subPaths) {
    if (subPath != null && subPath.contains("//")) {
        throw new IllegalArgumentException("subPath contains consecutive slashes: " + subPath);
    }
}
String url = HttpUtils.buildUrl(isHttps, serverAddr, subPaths);

try {
    url = HttpUtils.buildUrl(isHttps, serverAddr, subPaths);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Illegal url path expression")) {
        // Normalize all subPaths and retry
        String[] normalized = Arrays.stream(subPaths)
            .map(p -> p == null ? null : p.replaceAll("/+", "/"))
            .toArray(String[]::new);
        url = HttpUtils.buildUrl(isHttps, serverAddr, normalized);
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling HttpUtils.buildUrl(isHttps, serverAddr, subPaths) where one of the subPaths contains '//'. For example, buildUrl(false, "host:8848", "/nacos//v3") or buildUrl(false, "host:8848", "a//b").

Common situations: Programmatic URL construction that concatenates path segments without normalizing slashes; context paths that already end with '/' combined with resource paths that start with '/'; copy-paste from browser URLs that contain collapsed-path anomalies.

Related errors

• Illegal url path expression
• Unsupported http method : {name}
• httpClientFactory is null
• list size must be a multiple of 2
• MediaType must not be empty

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/7969704041ba364c. Report an issue: GitHub.