quarkusio/quarkus · error · IllegalArgumentException

Name parameter is null

Error message

Name parameter is null

What it means

IllegalArgumentException from UriBuilder.matrixParam(name, values): the matrix parameter name is null. JAX-RS matrix parameters require a name; a null name would make the resulting ';=value' segment meaningless, so the builder rejects it immediately before touching values.

Source

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

        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;
    }

    private static final Pattern PARAM_REPLACEMENT = Pattern.compile("_resteasy_uri_parameter");

    public UriBuilder replaceMatrixParam(String name, Object... values) throws IllegalArgumentException {
        if (name == null)

View on GitHub (pinned to e1c734241f)

Solutions

1. Ensure the name is non-null before calling matrixParam; fail fast with Objects.requireNonNull(name, "matrix param name")
2. Fix the source producing the null name (config key, map lookup, annotation value)
3. Skip the matrixParam call when the name is absent instead of passing null
4. Validate names against the expected set at startup (config mapping) so nulls surface early

Example fix

// before
builder.matrixParam(paramName, "v"); // paramName may be null
// after
Objects.requireNonNull(paramName, "matrix param name must not be null");
builder.matrixParam(paramName, "v");

if (name == null || name.isBlank()) { throw new IllegalStateException("Matrix param name required"); }
builder.matrixParam(name, value);

static boolean validMatrixName(String name) { return name != null && !name.isBlank(); }

try {
    builder.matrixParam(name, value);
} catch (IllegalArgumentException e) {
    if ("Name parameter is null".equals(e.getMessage())) {
        throw new IllegalStateException("Matrix parameter name was null; check config/source of name", e);
    }
    throw e;
}

When it happens

Trigger: matrixParam(someVariable, v1, v2) where the variable is null — typically an unset config value, an unannotated method parameter, or a name derived from a map key lookup that missed (map.get returns null).

Common situations: Names loaded from configuration or annotations that were absent; dynamic matrix params built from a Map whose key extraction returned null; refactor renamed the constant but not the call site.

Related errors

• name must not be null
• mediaType must not be null
• headerName must not be null
• headerValues must not be null
• newHeaders must not be null

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