quarkusio/quarkus · error · NullPointerException

Multipart field name filename cannot be null when sending fi

Error message

Multipart field name filename cannot be null when sending files

What it means

The Quarkus REST client multipart support throws this NullPointerException from the QuarkusMultipartFormDataPart(String name, String filename, String pathname, String mediaType, boolean text) constructor when the filename parameter is null. Every file-based multipart part must carry a filename because it is written into the Content-Disposition header of the part. The library fails fast rather than sending a malformed multipart body.

Source

Thrown at independent-projects/resteasy-reactive/client/runtime/src/main/java/org/jboss/resteasy/reactive/client/impl/multipart/QuarkusMultipartFormDataPart.java:94

        }
        this.name = name;
        this.value = value;
        this.filename = filename;
        this.pathname = null;
        this.content = null;
        this.multiByteContent = null;
        this.mediaType = null;
        this.text = false;
        this.isObject = false;
        this.type = null;
    }

    public QuarkusMultipartFormDataPart(String name, String filename, String pathname, String mediaType, boolean text) {
        if (name == null) {
            throw new NullPointerException("Multipart field name cannot be null");
        }
        if (filename == null) {
            throw new NullPointerException("Multipart field name filename cannot be null when sending files");
        }
        if (pathname == null) {
            throw new NullPointerException("Multipart field name pathname cannot be null when sending files");
        }
        if (mediaType == null) {
            throw new NullPointerException("Multipart field media type cannot be null");
        }
        this.name = name;
        this.value = null;
        this.filename = filename;
        this.pathname = pathname;
        this.content = null;
        this.multiByteContent = null;
        this.mediaType = mediaType;
        this.text = text;
        this.isObject = false;
        this.type = null;
    }

View on GitHub (pinned to e1c734241f)

Solutions

Pass a non-null filename (the file's base name) when creating the file upload part, e.g. new File(pathname).getName()
Ensure the MultipartForm API used is binaryFileUpload(name, filename, pathname, mediaType) with all four arguments supplied
Add a null/empty check on the filename variable before building the form

Example fix

// before
String filename = null;
form.binaryFileUpload("file", filename, "/tmp/data.bin", "application/octet-stream");
// after
String filename = new File("/tmp/data.bin").getName();
form.binaryFileUpload("file", filename, "/tmp/data.bin", "application/octet-stream");

Defensive patterns

Strategy: validation

Validate before calling

if (filename == null || filename.isBlank()) {
    throw new IllegalArgumentException("filename is required for multipart file upload");
}

Type guard

boolean hasValidFilename(String filename) {
    return filename != null && !filename.isBlank();
}

Prevention

Derive filenames with new File(path).getName() instead of passing raw nullable variables
Use IDE null-analysis or @NotNull annotations on upload helper parameters
Prefer the MultipartForm helper methods over constructing parts manually

When it happens

Trigger: Calling the constructor QuarkusMultipartFormDataPart(name, null, pathname, mediaType, text) with a null filename, or calling any higher-level API (e.g. MultipartForm binaryFileUpload/dataFileUpload variants) that forwards a null filename into this constructor.

Common situations: Building a multipart request where the filename is derived from a java.io.File or Path that was not normalized, or from a variable that is null; passing null explicitly because only the path seemed relevant; refactoring code that previously used a String path and losing the filename along the way.

Related errors

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