quarkusio/quarkus · error · IllegalArgumentException

Specified path can not contain '..' or '%'. Path was

Error message

Specified path can not contain '..' or '%'. Path was 

What it means

UriNormalizationUtil.toURI sanitizes root paths used for HTTP routes. Paths containing '..' (path traversal) or '%' (would be double-decoded) are rejected with this IllegalArgumentException to guarantee the configured route roots are safe and canonical.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/util/UriNormalizationUtil.java:42

     * <li>{@code toUri("foo/", false)} will return a URI with an empty path {@literal foo}</li>
     * </ul>
     *
     *
     * @param path String to convert into a URI
     * @param trailingSlash true if resulting URI must end with a '/'
     * @throws IllegalArgumentException if the path contains invalid characters or path segments.
     */
    public static URI toURI(String path, boolean trailingSlash) {
        try {
            // replace inbound // with /
            path = path.replaceAll("//", "/");
            // remove trailing slash if result shouldn't have one
            if (!trailingSlash && path.endsWith("/")) {
                path = path.substring(0, path.length() - 1);
            }

            if (path.contains("..") || path.contains("%")) {
                throw new IllegalArgumentException("Specified path can not contain '..' or '%'. Path was " + path);
            }
            URI uri = new URI(path).normalize();
            if (uri.getPath().equals("")) {
                return trailingSlash ? new URI("/") : new URI("");
            } else if (trailingSlash && !path.endsWith("/")) {
                uri = new URI(uri.getPath() + "/");
            }
            return uri;
        } catch (URISyntaxException e) {
            throw new IllegalArgumentException("Specified path is an invalid URI. Path was " + path, e);
        }
    }

    /**
     * Resolve a string path against a URI base. The specified path can not contain
     * relative {@literal ..} segments or {@literal %} characters.
     *
     * Relative paths will be resolved against the specified base URI.

View on GitHub (pinned to e1c734241f)

Solutions

1. Remove '..' segments; specify a plain absolute path like /api or / instead.
2. Remove or unescape '%' characters — configure the decoded value, not a percent-encoded one.
3. Resolve the intended logical path by hand and set the canonical result in configuration.
4. Validate externalized config values (env vars) before they reach Quarkus config.

Example fix

// before
quarkus.http.root-path=/api/../management
// after
quarkus.http.root-path=/management

static void validateRootPath(String path) {
    if (path == null || path.contains("..") || path.contains("%"))
        throw new IllegalArgumentException("Route root must not contain '..' or '%': " + path);
}

try { startApp(); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Specified path can not contain")) { /* fix root-path config value */ } else throw e; }

When it happens

Trigger: Configuring quarkus.http.root-path, quarkus.http.non-application-root-path, swagger/ui paths, or calling normalizeWithBase/segmentUri with a value containing '..' or '%'.

Common situations: Typos or copy-pasted paths like /api/../management; attempts to escape the application root in configuration; environment-variable-driven path config that includes encoded characters (%2F etc.).

Related errors

• Specified path is an invalid URI. Path was
• The value of URL was invalid " + baseUrl
• Invalid REST Client URL used: '<uri>'
• empty host
• Failed to load application configuration

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/066900127f622118. Report an issue: GitHub.