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

Pass a valid header name literal, e.g. header("Content-Disposition", ...).

quarkusio/quarkus · error · IllegalArgumentException

headerName must not be null

Error message

headerName must not be null

What it means

EntityPart.Builder.header(String, String...) adds a header to the part; the header name is mandatory per the Jakarta REST spec, so a null name throws IllegalArgumentException. Header values are validated separately.

Source

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

            throw new IllegalArgumentException("mediaType must not be null");
        }
        this.mediaType = mediaType;
        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;

View on GitHub (pinned to e1c734241f)

Solutions

Pass a valid header name literal, e.g. header("Content-Disposition", ...).
Filter out null keys before copying headers from a map into the builder.
Fix the source collection so header names are never null.
Validate header names (non-null, valid token) before adding.

Example fix

// before
for (Entry<String, String> h : headerMap.entrySet()) {
    builder.header(h.getKey(), h.getValue()); // key may be null
}

// after
headerMap.entrySet().stream()
    .filter(h -> h.getKey() != null)
    .forEach(h -> builder.header(h.getKey(), h.getValue()));

Defensive patterns

Strategy: validation

Validate before calling

if (headerName != null) {
    builder.header(headerName, headerValue);
}

Type guard

boolean hasHeaderName(String name) {
    return name != null && !name.isEmpty();
}

Try / catch

try {
    builder.header(name, value);
} catch (IllegalArgumentException e) {
    log.warn("Skipping part header with null name");
}

Prevention

Filter null keys when copying headers from maps.
Use literals for well-known header names (Content-Disposition, Content-Type).
Validate header names as valid HTTP tokens before adding.

When it happens

Trigger: Calling partBuilder.header(null, "value") or passing a null header name obtained from iteration/lookup.

Common situations: Looping over a map whose keys can be null, or copying headers from another request where a name was never set; dynamic header construction from config keys.

Related errors

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