quarkusio/quarkus · error · IllegalArgumentException

Illegal URI template${uriTemplate}

Error message

Illegal URI template${uriTemplate}

What it means

UriBuilderImpl.uriTemplate() throws this IllegalArgumentException when the given URI template matches neither the opaque-URI pattern nor the hierarchical-URI pattern used internally to parse templates. This is the RESTEasy Reactive implementation of the JAX-RS UriBuilder.uri(String) contract, which mandates IllegalArgumentException for malformed input. The message concatenates the offending template with no space, so it reads like 'Illegal URI templatehttp://...'.

Source

Thrown at independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/common/jaxrs/UriBuilderImpl.java:182

            throw new IllegalArgumentException("Param was null");
        Matcher opaque = opaqueUri.matcher(uriTemplate);
        if (opaque.matches()) {
            this.authority = null;
            this.host = null;
            this.port = -1;
            this.userInfo = null;
            this.query = null;
            this.scheme = opaque.group(1);
            this.ssp = opaque.group(2);
            return this;
        } else {
            Matcher match = hierarchicalUri.matcher(uriTemplate);
            if (match.matches()) {
                ssp = null;
                return parseHierarchicalUri(uriTemplate, match);
            }
        }
        throw new IllegalArgumentException("Illegal URI template" + uriTemplate);
    }

    protected UriBuilder parseHierarchicalUri(CharSequence uriTemplate, Matcher match) {
        boolean scheme = match.group(2) != null;
        if (scheme)
            this.scheme = match.group(2);
        String authority = match.group(4);
        if (authority != null) {
            this.authority = null;
            String host = match.group(4);
            int at = host.indexOf('@');
            if (at > -1) {
                String user = host.substring(0, at);
                host = host.substring(at + 1);
                this.userInfo = user;
            }

            Matcher hostPortMatch = hostPortPattern.matcher(host);

View on GitHub (pinned to e1c734241f)

Solutions

1. URI-encode variable parts (URLEncoder.encode with UTF-8) before calling uri()/uriTemplate()
2. Fix the configured base URL (e.g. quarkus.rest-client.*.url): remove spaces, stray brackets, double slashes
3. Build the URI with builder methods (scheme/host/port/path/queryParam) instead of one raw string
4. Catch IllegalArgumentException around uri()/uriTemplate() and log the offending template for diagnosis

Example fix

// before: UriBuilder.fromUri(userInput) throws for 'http://example .com' // after: String cleaned = userInput.trim().replace(' ', '%20'); URI uri = UriBuilder.fromUri(cleaned).build();

static void validateUriTemplate(String template) {
    java.util.Objects.requireNonNull(template, 'template must not be null');
    String t = template.trim();
    if (t.isEmpty()) throw new IllegalArgumentException('template is empty');
    if (t.contains(" ")) throw new IllegalArgumentException('template contains unencoded space');
    if (!t.matches('^[a-zA-Z][a-zA-Z0-9+.-]*:.*') && !t.startsWith('/'))
        throw new IllegalArgumentException('template must include a scheme: ' + template);
}

try {
    URI uri = UriBuilder.fromUri(template).build();
} catch (IllegalArgumentException e) {
    throw new IllegalArgumentException('Invalid URI template: ' + template, e);
}

When it happens

Trigger: Calling uriTemplate/fromTemplate/uri/uriFromCharSequence/resolveTemplate(s)/resolveTemplateFromEncoded with a string matching neither internal regex: e.g. 'http:////bad', a scheme-only string like 'http:', or strings with characters illegal anywhere in a URI (unencoded spaces, stray brackets, unencoded braces outside template params).

Common situations: Base URLs from config or user input containing spaces or unencoded special characters; hand-concatenating scheme/authority parts; forgetting to URL-encode path/query values embedded in the template; framework upgrades tightening the parsing regexes.

Related errors

• URI is null
• Scheme was null
• invalid host
• invalid port
• path is null

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