{"record":{"id":"642b0458fecf0365","repo":"halo-dev/halo","slug":"the-avatar-file-needs-to-be-smaller-than-mb","errorCode":null,"errorMessage":"The avatar file needs to be smaller than {} MB.","messagePattern":"The avatar file needs to be smaller than (.+?) MB\\.","errorType":"validation","errorClass":"ServerWebInputException","httpStatus":400,"severity":"error","filePath":"application/src/main/java/run/halo/app/core/endpoint/console/UserEndpoint.java","lineNumber":448,"sourceCode":"                .defaultIfEmpty(DEFAULT_USER_AVATAR_ATTACHMENT_POLICY_NAME);\n        return getAvatarPolicy.flatMap(avatarPolicy -> {\n            FilePart filePart = uploadRequest.getFile();\n            var ext = Files.getFileExtension(filePart.filename());\n            return attachmentService.upload(\n                    avatarPolicy,\n                    USER_AVATAR_GROUP_NAME,\n                    UUID.randomUUID() + \".\" + ext,\n                    maxSizeCheck(filePart.content()),\n                    filePart.headers().getContentType());\n        });\n    }\n\n    private Flux<DataBuffer> maxSizeCheck(Flux<DataBuffer> content) {\n        var lenRef = new AtomicInteger(0);\n        return content.doOnNext(dataBuffer -> {\n            int len = lenRef.accumulateAndGet(dataBuffer.readableByteCount(), Integer::sum);\n            if (len > MAX_AVATAR_FILE_SIZE.toBytes()) {\n                throw new ServerWebInputException(\n                        \"The avatar file needs to be smaller than \" + MAX_AVATAR_FILE_SIZE.toMegabytes() + \" MB.\");\n            }\n        });\n    }\n\n    private Mono<ServerResponse> createUser(ServerRequest request) {\n        return request.bodyToMono(CreateUserRequest.class)\n                .doOnNext(createUserRequest -> {\n                    if (StringUtils.isBlank(createUserRequest.name())) {\n                        throw new ServerWebInputException(\"Name is required\");\n                    }\n                    if (StringUtils.isBlank(createUserRequest.email())) {\n                        throw new ServerWebInputException(\"Email is required\");\n                    }\n                })\n                .flatMap(userRequest -> {\n                    User newUser = CreateUserRequest.from(userRequest);\n                    var encryptedPwd = userService.encryptPassword(userRequest.password());","sourceCodeStart":430,"sourceCodeEnd":466,"githubUrl":"https://github.com/halo-dev/halo/blob/d2f5165f9c8f055ffcb3fa9c3f4032821a7b68c8/application/src/main/java/run/halo/app/core/endpoint/console/UserEndpoint.java#L430-L466","documentation":"Thrown as a ServerWebInputException (HTTP 400) inside maxSizeCheck while streaming the avatar's DataBuffer content. An AtomicInteger accumulates readable bytes; once the running total exceeds MAX_AVATAR_FILE_SIZE, the stream is aborted with a message naming the megabyte limit. The check is per-buffer, so the upload is rejected mid-stream rather than buffered fully.","triggerScenarios":"POST to the avatar upload endpoint with a file whose total content size exceeds MAX_AVATAR_FILE_SIZE (the configured megabyte cap). The exception fires as soon as the cumulative bytes cross the threshold.","commonSituations":"User uploads a high-res phone photo directly; animated GIF oversized; default size cap too small for the organization's needs; frontend lacks a pre-upload size check.","solutions":["Compress or resize the image so its byte size is under the configured MAX_AVATAR_FILE_SIZE before uploading.","Add a client-side size guard (check File.size) and reject oversized files before the request.","If the policy allows, raise MAX_AVATAR_FILE_SIZE in configuration to fit expected avatars."],"exampleFix":"// before: upload a 12 MB photo with a 2 MB cap\n// after: resize to <=256px and compress before upload so size < cap","handlingStrategy":"validation","validationCode":"// guard on byte size before uploading\nlong MAX = MAX_AVATAR_FILE_SIZE.toBytes(); // mirror server cap\nif (selectedFile.length() > MAX) {\n    showUserError(\"File must be smaller than \" + (MAX / 1_000_000) + \" MB\");\n    return;\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check File.size on the client and reject oversized files pre-upload.","Resize/compress avatars to a small square before upload."],"tags":["user","avatar","upload","size-limit","streaming"],"backgroundTag":null,"analyzedSha":"d2f5165f9c8f055ffcb3fa9c3f4032821a7b68c8","analyzedAt":"2026-08-14T00:18:38.915Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}