What causes "headerValues must not be null" in quarkusio/quarkus?

Pass at least one non-null value, or call header(name) with a single empty string if an empty header is intended.

quarkusio/quarkus · error · IllegalArgumentException

headerValues must not be null

Error message

headerValues must not be null

What it means

EntityPart.Builder.header(String, String...) validates that the varargs headerValues array itself is not null. A null array (distinct from an empty one or a null element) throws IllegalArgumentException immediately.

Source

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

        return this;
    }

    @Override
    public EntityPart.Builder mediaType(String mediaTypeString) throws IllegalArgumentException {
        if (mediaTypeString == null) {
            throw new IllegalArgumentException("mediaType must not be null");
        }
        this.mediaType = MediaType.valueOf(mediaTypeString);
        return this;
    }

    @Override
    public EntityPart.Builder header(String headerName, String... headerValues) throws IllegalArgumentException {
        if (headerName == null) {
            throw new IllegalArgumentException("headerName must not be null");
        }
        if (headerValues == null) {
            throw new IllegalArgumentException("headerValues must not be null");
        }
        for (String value : headerValues) {
            headers.add(headerName, value);
        }
        return this;
    }

    @Override
    public EntityPart.Builder headers(MultivaluedMap<String, String> newHeaders) throws IllegalArgumentException {
        if (newHeaders == null) {
            throw new IllegalArgumentException("newHeaders must not be null");
        }
        this.headers = new QuarkusMultivaluedHashMap<>();
        this.headers.putAll(newHeaders);
        return this;
    }

    @Override

View on GitHub (pinned to e1c734241f)

Solutions

Pass at least one non-null value, or call header(name) with a single empty string if an empty header is intended.
Coerce null arrays to an empty array or skip the call when values are absent.
Fix the upstream producer of the values array so it returns an empty array instead of null.
Validate the array before invoking header(...).

Example fix

// before
builder.header("X-Token", values); // values may be null

// after
if (values != null && values.length > 0) {
    builder.header("X-Token", values);
}

Defensive patterns

Strategy: validation

Validate before calling

if (values != null && values.length > 0) {
    builder.header(name, values);
}

Type guard

String[] nonEmpty(String[] v) {
    return v != null ? v : new String[0];
}

Try / catch

try {
    builder.header(name, values);
} catch (IllegalArgumentException e) {
    log.warn("Skipping header " + name + ": null values array");
}

Prevention

Return empty arrays instead of null from value-producing methods.
Check array length before calling varargs header(...).
Avoid casting null to String[] when calling varargs APIs.

When it happens

Trigger: Calling partBuilder.header("X-Custom", (String[]) null) or passing a null String[] variable as values.

Common situations: Forwarding a nullable values array from another method's return; calling header via reflection or with a cast null varargs.

Related errors

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