halo-dev/halo · warning · ServerWebInputException

Invalid part of policyName

Error message

Invalid part of policyName

What it means

UploadRequest.getPolicyName() throws ServerWebInputException (HTTP 400) 'Invalid part of policyName' when the multipart form has no "policyName" part or the part is not a FormFieldPart. Unlike getGroupName (which returns null when absent), policyName is mandatory for an upload.

Source

Thrown at application/src/main/java/run/halo/app/core/attachment/endpoint/AttachmentEndpoint.java:176

        /** Attachment group {@code metadata.name}. */
        String getGroupName();
    }

    public record UploadRequest(MultiValueMap<String, Part> formData) implements IUploadRequest {

        public FilePart getFile() {
            if (formData.getFirst("file") instanceof FilePart file) {
                return file;
            }
            throw new ServerWebInputException("Invalid part of file");
        }

        public String getPolicyName() {
            if (formData.getFirst("policyName") instanceof FormFieldPart form) {
                return form.value();
            }
            throw new ServerWebInputException("Invalid part of policyName");
        }

        @Override
        public String getGroupName() {
            if (formData.getFirst("groupName") instanceof FormFieldPart form) {
                return form.value();
            }
            return null;
        }
    }
}

View on GitHub (pinned to d2f5165f9c)

Solutions

1. Append a policyName form field (string) to the multipart body alongside file.
2. On the client, always send policyName even if you also send groupName.
3. Validate that the policy exists before initiating the upload.

Example fix

// before
fd.append('file', selectedFile); // no policyName

// after
fd.append('file', selectedFile);
fd.append('policyName', 'default-policy');

if (!(formData.getFirst("policyName") instanceof FormFieldPart f)) {
    return Mono.error(new ServerWebInputException("Invalid part of policyName"));
}

static boolean hasPolicyNamePart(MultiValueMap<String, Part> fd) {
    return fd.getFirst("policyName") instanceof FormFieldPart;
}

When it happens

Trigger: Multipart upload missing the policyName field; policyName sent as a file part by mistake; client forgot to append the form field.

Common situations: Frontend bug that only appends the file part; copy-paste of upload code that omitted the policyName append; a third-party uploader that doesn't know Halo requires policyName.

Related errors

• Required url is missing.
• Policy name must not be blank
• Invalid part of file
• urls must not be empty.
• Form field file is required

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