quarkusio/quarkus · error · UriBuilderException

failed to create URI

Error message

failed to create URI

What it means

UriBuilderException wrapping a failure from new URI(buf) in buildFromValues: the fully substituted template string could not be parsed as a URI. Unlike the IllegalArgumentException cases (missing/null params) which pass through unchanged, this fires after substitution succeeded but the resulting string is malformed (illegal characters or bad URI structure). The original exception is chained as the cause.

Source

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

        }
    }

    public URI build(Object... values) throws IllegalArgumentException, UriBuilderException {
        if (values == null)
            throw new IllegalArgumentException("Values parameter is null");
        return buildFromValues(true, false, values);
    }

    protected URI buildFromValues(boolean encodeSlash, boolean encoded, Object... values) {
        String buf = null;
        try {
            buf = buildString(new URITemplateParametersMap(values), encoded, false, encodeSlash);
            return new URI(buf);
            //return URI.create(buf);
        } catch (IllegalArgumentException iae) {
            throw iae;
        } catch (Exception e) {
            throw new UriBuilderException("failed to create URI", e);
        }
    }

    public UriBuilder matrixParam(String name, Object... values) throws IllegalArgumentException {
        if (name == null)
            throw new IllegalArgumentException("Name parameter is null");
        if (values == null)
            throw new IllegalArgumentException("Values parameter is null");
        if (path == null)
            path = "";
        for (Object val : values) {
            if (val == null)
                throw new IllegalArgumentException("Value is null");
            String matrixName = encode ? Encode.encodeMatrixParam(name) : name;
            String matrixValue = encode ? Encode.encodeMatrixParam(val.toString()) : val.toString();
            path += ";" + matrixName + "=" + matrixValue;
        }
        return this;

View on GitHub (pinned to e1c734241f)

Solutions

1. Read e.getCause() (URISyntaxException) for the exact index and reason of the parse failure
2. Encode values before building: use Encode/URLEncoder for path segments and query params, or call build() with encoding enabled (encoded=false)
3. If values are legitimately already encoded, strip or escape stray reserved characters ('{', '}', space) before passing them
4. Construct via UriBuilder path()/queryParam() methods rather than string concatenation so each component is encoded correctly

Example fix

// before
URI u = UriBuilder.fromUri("/files/{name}").buildFromValues(false, true, "my file.txt"); // claims pre-encoded
// after
URI u = UriBuilder.fromUri("/files/{name}").build(URLEncoder.encode("my file.txt", StandardCharsets.UTF_8));

// pre-validate values are URI-safe or already encoded
for (Object v : values) {
    String s = String.valueOf(v);
    if (s.chars().anyMatch(c -> c <= 32 || c == '{' || c == '}' || c > 127)) {
        throw new IllegalArgumentException("Value needs URI encoding: " + s);
    }
}

static boolean isEncoded(String s) { return s != null && java.util.stream.IntStream.of(s.chars().toArray()).noneMatch(c -> c <= 32 || c == '{' || c == '}'); }

try {
    URI uri = builder.build(values);
} catch (UriBuilderException e) {
    throw new IllegalStateException("Built URI string invalid: " + (e.getCause() != null ? e.getCause().getMessage() : e.getMessage()), e);
}

When it happens

Trigger: build(Object...)/buildFromValues where a substituted value contains characters illegal in a URI component (space, '{', control chars, non-ASCII) and the encoding flag (encoded=true path) skipped escaping, or the template itself forms a bad URI once values are inserted.

Common situations: Using buildFromValues(..., encoded=true, ...) with values that are not actually pre-encoded; inserting user input into path segments without encoding; values containing '{'/'}' left over from nested templates; scheme or authority fragments glued together incorrectly.

Related errors

• Failed to create URI
• Illegal URI template${uriTemplate}
• URI is null
• Scheme was null
• invalid host

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