quarkusio/quarkus · error · IllegalArgumentException

Specified path is an invalid URI. Path was

Error message

Specified path is an invalid URI. Path was

What it means

After sanitization, toURI constructs a java.net.URI from the path; if the string is not a syntactically valid URI (illegal characters such as spaces, braces, or other reserved chars), the URISyntaxException is rethrown as this IllegalArgumentException with the offending path. It guards route-root configuration from malformed values.

Source

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

            // 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.
     * Absolute paths will be normalized and returned.
     * <p>
     * Examples:
     * <ul>
     * <li>{@code normalizeWithBase(new URI("/"), "example", true)}
     * will return a URI with path {@literal /example/}</li>
     * <li>{@code normalizeWithBase(new URI("/"), "example", false)}
     * will return a URI with an empty path {@literal /example}</li>
     * <li>{@code normalizeWithBase(new URI("/"), "/example", true)}
     * will return a URI with path {@literal /example/}</li>

View on GitHub (pinned to e1c734241f)

Solutions

  1. Percent-encode or remove illegal characters, or quote the value properly: use /my-app instead of /my app.
  2. Inspect the full error message for the exact path and fix the offending characters.
  3. Check config sources (env vars, profiles) for unresolved placeholders like ${VAR}.
  4. Normalize the string yourself (URI encode) before passing it to Quarkus configuration.

Example fix

# before
quarkus.http.root-path=/my app
# after
quarkus.http.root-path=/my-app
Defensive patterns

Strategy: validation

Validate before calling

static boolean isValidUriPath(String path) {
    try { new java.net.URI(path); return true; } catch (java.net.URISyntaxException e) { return false; }
}

Try / catch

try { startApp(); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Specified path is an invalid URI")) { /* fix or percent-encode the path config */ } else throw e; }

Prevention

When it happens

Trigger: Setting quarkus.http.root-path / non-application-root-path or calling UriNormalizationUtil.normalizeWithBase/segmentUri with a path containing characters illegal in a URI (space, '{', '}', '|', non-ASCII chars, etc.).

Common situations: Paths with spaces ("/my app"), unencoded special characters pasted from documentation, template placeholders or env interpolation leaving ${...} remnants in config values.

Related errors

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