{"record":{"id":"bd5c8f3aa053345d","repo":"quarkusio/quarkus","slug":"template-parameter-null","errorCode":null,"errorMessage":"Template parameter null: ","messagePattern":"Template parameter null: ","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/common/jaxrs/UriBuilderImpl.java","lineNumber":640,"sourceCode":"        }\n        Matcher matcher = createUriParamMatcher(string);\n        int start = 0;\n        while (matcher.find()) {\n            builder.append(string, start, matcher.start());\n            String param = matcher.group(1);\n            boolean containsValueForParam = paramMap.containsKey(param);\n            if (!containsValueForParam) {\n                if (isTemplate) {\n                    builder.append(matcher.group());\n                    start = matcher.end();\n                    continue;\n                }\n                throw new IllegalArgumentException(\"Path parameter not provided \" + param);\n            }\n            Object value = paramMap.get(param);\n            String stringValue = value != null ? value.toString() : null;\n            if (stringValue == null) {\n                throw new IllegalArgumentException(\"Template parameter null: \" + param);\n            }\n\n            if (encode) {\n                if (!fromEncodedMap) {\n                    if (encodeSlash)\n                        stringValue = Encode.encodePathSegmentAsIs(stringValue);\n                    else\n                        stringValue = Encode.encodePathAsIs(stringValue);\n                } else {\n                    if (encodeSlash)\n                        stringValue = Encode.encodePathSegmentSaveEncodings(stringValue);\n                    else\n                        stringValue = Encode.encodePathSaveEncodings(stringValue);\n                }\n            }\n\n            builder.append(stringValue);\n            start = matcher.end();","sourceCodeStart":622,"sourceCodeEnd":658,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/common/jaxrs/UriBuilderImpl.java#L622-L658","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nMap<String, Object> params = new HashMap<>();\nparams.put(\"id\", maybeId.orElse(null));\nURI u = UriBuilder.fromUri(\"/users/{id}\").build(params);\n// after\nint id = maybeId.orElseThrow(() -> new IllegalStateException(\"id is required\"));\nURI u = UriBuilder.fromUri(\"/users/{id}\").build(Map.of(\"id\", id));","handlingStrategy":"validation","validationCode":"paramMap.forEach((k, v) -> { if (v == null) throw new IllegalArgumentException(\"URI template param '\" + k + \"' is null\"); });","typeGuard":"static boolean allValuesNonNull(Map<String, ?> params) { return params.values().stream().allMatch(java.util.Objects::nonNull); }","tryCatchPattern":"try {\n    URI uri = builder.build(params);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"Template parameter null\")) {\n        String param = e.getMessage().substring(e.getMessage().lastIndexOf(':') + 1).trim();\n        throw new IllegalStateException(\"Null value supplied for URI param '\" + param + \"'\", e);\n    }\n    throw e;\n}","preventionTips":["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"],"tags":["uri","resteasy-reactive","null-value"],"backgroundTag":"missing-uri-template-parameter","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}