quarkusio/quarkus · error · IllegalArgumentException

Template parm was null:

Error message

Template parm was null: 

What it means

IllegalArgumentException thrown from the query-parameter replacement method when the value looked up for a {placeholder} in a query template is null. It is the query-string sibling of 'Template parameter null': the key resolved (or was present) but the value is null, so no valid substitution exists for a concrete URI.

Source

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

                if (isTemplate) {
                    builder.append(matcher.group());
                    start = matcher.end();
                    continue;
                }
                throw new IllegalArgumentException("Path parameter not provided " + param);
            }
            Object value = paramMap.get(param);
            String stringValue = value != null ? value.toString() : null;
            if (stringValue != null) {
                if (!fromEncodedMap) {
                    stringValue = Encode.encodeQueryParamAsIs(stringValue);
                } else {
                    stringValue = Encode.encodeQueryParamSaveEncodings(stringValue);
                }
                builder.append(stringValue);
                start = matcher.end();
            } else {
                throw new IllegalArgumentException("Template parm was null: " + param);
            }
        }
        builder.append(string, start, string.length());
        return builder;
    }

    /**
     * Return a unique order list of path params.
     *
     * @return list of path parameters
     */
    public List<String> getPathParamNamesInDeclarationOrder() {
        List<String> params = new ArrayList<String>();
        HashSet<String> set = new HashSet<String>();
        if (scheme != null)
            addToPathParamList(params, set, scheme);
        if (userInfo != null)
            addToPathParamList(params, set, userInfo);

View on GitHub (pinned to e1c734241f)

Solutions

1. Null-check every varargs value before build() and substitute a default (e.g. empty string) where semantically valid
2. Unwrap Optionals with orElseThrow instead of orElse(null) when the parameter is required
3. Conditionally add the queryParam only when the value is non-null, keeping the template free of that {token}
4. Wrap build() in a helper that validates values and rethrows with the parameter name for diagnosis

Example fix

// before
URI u = UriBuilder.fromUri("/search").queryParam("q", "{term}").build(term); // term may be null
// after
URI u = term == null
    ? UriBuilder.fromUri("/search").build()
    : UriBuilder.fromUri("/search").queryParam("q", term).build();

for (Object v : values) { if (v == null) throw new IllegalArgumentException("URI template values must be non-null"); }
URI uri = builder.build(values);

static boolean allNonNull(Object[] values) { return values != null && java.util.Arrays.stream(values).allMatch(java.util.Objects::nonNull); }

try {
    URI uri = builder.build(values);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Template parm was null")) {
        throw new IllegalStateException("Null value in URI template varargs: " + e.getMessage(), e);
    }
    throw e;
}

When it happens

Trigger: build(Object... values) / buildFromValues where one of the values for a {token} in a queryParam template string is null; the count matched but an element was null, so URITemplateParametersMap yields null for that param.

Common situations: Passing nullable variables directly as varargs: build(term) where term is null; Optional handling that unwraps to null; test fixtures with missing data; bean properties that are null at call time.

Related errors

• Template parameter null:
• 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/a87b573751e71c03. Report an issue: GitHub.