halo-dev/halo · error · ServerWebInputException

No file part found in the request

Error message

No file part found in the request

What it means

Thrown as a ServerWebInputException (HTTP 400) by AvatarUploadRequest.getFile() when formData.getFirst("file") returns null — i.e. the multipart request to the avatar upload endpoint contains no part named 'file' at all.

Source

Thrown at application/src/main/java/run/halo/app/core/endpoint/console/UserEndpoint.java:401

                        })
                        .retryWhen(Retry.backoff(5, Duration.ofMillis(100))
                                .filter(OptimisticLockingFailureException.class::isInstance)))
                .flatMap(user -> ServerResponse.ok().bodyValue(user));
    }

    /** Multipart payload for uploading a user avatar. */
    @Schema(types = "object")
    public interface IAvatarUploadRequest {
        /** Avatar file. */
        @Schema(requiredMode = REQUIRED)
        FilePart getFile();
    }

    public record AvatarUploadRequest(MultiValueMap<String, Part> formData) {
        public FilePart getFile() {
            Part file = formData.getFirst("file");
            if (file == null) {
                throw new ServerWebInputException("No file part found in the request");
            }

            if (!(file instanceof FilePart filePart)) {
                throw new ServerWebInputException("Invalid part of file");
            }

            boolean isNoneExt = Arrays.stream(ALLOWED_AVATAR_EXTENSIONS)
                    .noneMatch(ext -> filePart.filename().endsWith("." + ext));

            if (isNoneExt) {
                throw new ServerWebInputException(
                        "Only support file with extension: " + String.join(", ", ALLOWED_AVATAR_EXTENSIONS));
            }
            return filePart;
        }
    }

    private Mono<Attachment> uploadAvatar(AvatarUploadRequest uploadRequest) {

View on GitHub (pinned to d2f5165f9c)

Solutions

  1. Ensure the multipart request includes a part literally named 'file' containing the avatar binary.
  2. Double-check the client-side field name matches 'file' exactly.
  3. Verify the request Content-Type is multipart/form-data and the boundary is present.

Example fix

// before: curl -F avatar=@me.png /users/-/avatar
// after:  curl -F file=@me.png   /users/-/avatar
Defensive patterns

Strategy: validation

Validate before calling

// ensure a File (or FormData File entry) is selected before submit
if (selectedFile == null) {
    showUserError("Select an avatar file first");
    return;
}
formData.append("file", selectedFile); // exact field name 'file'

Prevention

When it happens

Trigger: POST to the user-center/console avatar upload endpoint with a multipart body that omits the 'file' field, or sends the file under a different field name (e.g. 'avatar', 'image', 'upload').

Common situations: Frontend uses the wrong form field name; the file picker returned no selection and the form was still submitted; a curl/Postman request forgot the -F 'file=@...' part; integration test posts an empty multipart body.

Related errors

AI-assisted analysis of halo-dev/halo@d2f5165f9c (2026-08-14). Data as JSON: /api/errors/c1be622226a2eda2. Report an issue: GitHub.