quarkusio/quarkus · error · IllegalArgumentException

newHeaders must not be null

Error message

newHeaders must not be null

What it means

EntityPart.Builder.headers(MultivaluedMap) replaces the part's entire header map; a null map cannot be copied and throws IllegalArgumentException. The builder defensively clears and re-populates from the provided map.

Source

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

    @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
    public EntityPart.Builder fileName(String fileName) throws IllegalArgumentException {
        this.fileName = fileName;
        return this;
    }

    @Override
    public EntityPart.Builder content(InputStream content) throws IllegalArgumentException {
        if (content == null) {
            throw new IllegalArgumentException("content must not be null");
        }
        this.content = content;

View on GitHub (pinned to e1c734241f)

Solutions

1. Pass an actual MultivaluedMap; use a new empty QuarkusMultivaluedHashMap/MultivaluedHashMap when there are no headers.
2. Skip the headers(...) call entirely when the source map is null.
3. Fix the getter producing the map to return an empty map instead of null.
4. Guard the call with a null check before replacing headers.

Example fix

// before
builder.headers(existingHeaders); // may be null

// after
if (existingHeaders != null) {
    builder.headers(existingHeaders);
}

if (newHeaders != null) {
    builder.headers(newHeaders);
}

MultivaluedMap<String, String> orEmpty(MultivaluedMap<String, String> m) {
    return m != null ? m : new MultivaluedHashMap<>();
}

try {
    builder.headers(newHeaders);
} catch (IllegalArgumentException e) {
    builder.headers(new MultivaluedHashMap<>());
}

When it happens

Trigger: Calling partBuilder.headers(null), typically when the replacement map comes from a method or lookup that returned null.

Common situations: Copying headers from a response/request object where the map getter returned null; optional header sets that are absent by design.

Related errors

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

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