quarkusio/quarkus · error · IllegalArgumentException
Template parameter null:
Error message
Template parameter null:
What it means
IllegalArgumentException from replaceParameter when the parameter map contains an entry whose value toString()s to null — effectively the map has the key mapped to null and containsValueForParam was true but stringValue is still null. Distinguishes 'key present but null' from 'key missing' (the latter throws 'Path parameter not provided'). JAX-RS refuses to substitute null into a concrete URI.
Source
Thrown at independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/common/jaxrs/UriBuilderImpl.java:640
}
Matcher matcher = createUriParamMatcher(string);
int start = 0;
while (matcher.find()) {
builder.append(string, start, matcher.start());
String param = matcher.group(1);
boolean containsValueForParam = paramMap.containsKey(param);
if (!containsValueForParam) {
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) {
throw new IllegalArgumentException("Template parameter null: " + param);
}
if (encode) {
if (!fromEncodedMap) {
if (encodeSlash)
stringValue = Encode.encodePathSegmentAsIs(stringValue);
else
stringValue = Encode.encodePathAsIs(stringValue);
} else {
if (encodeSlash)
stringValue = Encode.encodePathSegmentSaveEncodings(stringValue);
else
stringValue = Encode.encodePathSaveEncodings(stringValue);
}
}
builder.append(stringValue);
start = matcher.end();View on GitHub (pinned to e1c734241f)
Solutions
- Check the map for null values before calling build() and default or reject them
- Use Objects.requireNonNull on each template value to fail fast at the call site with a clearer message
- Filter out entries with null values only if the placeholder is optional — otherwise supply a real value
- Wrap the value lookup so an absent Optional becomes a validation error rather than a null map entry
Example fix
// before
Map<String, Object> params = new HashMap<>();
params.put("id", maybeId.orElse(null));
URI u = UriBuilder.fromUri("/users/{id}").build(params);
// after
int id = maybeId.orElseThrow(() -> new IllegalStateException("id is required"));
URI u = UriBuilder.fromUri("/users/{id}").build(Map.of("id", id)); Defensive patterns
Strategy: validation
Validate before calling
paramMap.forEach((k, v) -> { if (v == null) throw new IllegalArgumentException("URI template param '" + k + "' is null"); }); Type guard
static boolean allValuesNonNull(Map<String, ?> params) { return params.values().stream().allMatch(java.util.Objects::nonNull); } Try / catch
try {
URI uri = builder.build(params);
} catch (IllegalArgumentException e) {
if (e.getMessage().startsWith("Template parameter null")) {
String param = e.getMessage().substring(e.getMessage().lastIndexOf(':') + 1).trim();
throw new IllegalStateException("Null value supplied for URI param '" + param + "'", e);
}
throw e;
} Prevention
- Avoid Optional.orElse(null) for values destined for URI templates; use orElseThrow
- Null-check DTO fields before placing them into a parameter map
- Prefer Map.of over HashMap for parameter maps so nulls are rejected at insertion time
When it happens
Trigger: Calling UriBuilder.build(Map)/buildFromMap with a HashMap that explicitly maps a placeholder name to null, e.g. Map.of does not allow null but HashMap.put("id", null) does, then building a concrete (non-template) URI.
Common situations: Populating the parameter map from Optional.orElse(null), from a request/response DTO field that is null, or from variables not yet initialized; upstream refactors changing a value from non-null to nullable.
Related errors
AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05).
Data as JSON: /api/errors/bd5c8f3aa053345d.
Report an issue: GitHub.