{"id":"a80226f57b796281","repo":"gin-gonic/gin","slug":"unsupported-len-of-array-for-multipart-filehead","errorCode":null,"errorMessage":"unsupported len of array for []*multipart.FileHeader","messagePattern":"unsupported len of array for \\[\\]\\*multipart\\.FileHeader","errorType":"validation","errorClass":"ErrMultiFileHeaderLenInvalid","httpStatus":400,"severity":"error","filePath":"binding/multipart_form_mapping.go","lineNumber":23,"sourceCode":"package binding\n\nimport (\n\t\"errors\"\n\t\"mime/multipart\"\n\t\"net/http\"\n\t\"reflect\"\n)\n\ntype multipartRequest http.Request\n\nvar _ setter = (*multipartRequest)(nil)\n\nvar (\n\t// ErrMultiFileHeader multipart.FileHeader invalid\n\tErrMultiFileHeader = errors.New(\"unsupported field type for multipart.FileHeader\")\n\n\t// ErrMultiFileHeaderLenInvalid array for []*multipart.FileHeader len invalid\n\tErrMultiFileHeaderLenInvalid = errors.New(\"unsupported len of array for []*multipart.FileHeader\")\n)\n\n// TrySet tries to set a value by the multipart request with the binding a form file\nfunc (r *multipartRequest) TrySet(value reflect.Value, field reflect.StructField, key string, opt setOptions) (bool, error) {\n\tif files := r.MultipartForm.File[key]; len(files) != 0 {\n\t\treturn setByMultipartFormFile(value, field, files)\n\t}\n\n\treturn setByForm(value, field, r.MultipartForm.Value, key, opt)\n}\n\nfunc setByMultipartFormFile(value reflect.Value, field reflect.StructField, files []*multipart.FileHeader) (isSet bool, err error) {\n\tswitch value.Kind() {\n\tcase reflect.Ptr:\n\t\tswitch value.Interface().(type) {\n\t\tcase *multipart.FileHeader:\n\t\t\tvalue.Set(reflect.ValueOf(files[0]))\n\t\t\treturn true, nil","sourceCodeStart":5,"sourceCodeEnd":41,"githubUrl":"https://github.com/gin-gonic/gin/blob/34dac209ffb6ef85cc78c5d217bbb7ad001d68fd/binding/multipart_form_mapping.go#L5-L41","documentation":"ErrMultiFileHeaderLenInvalid is returned by setArrayOfMultipartFormFiles (binding/multipart_form_mapping.go:65) when the destination is a fixed-length array ([N]*multipart.FileHeader or [N]multipart.FileHeader) and the number of uploaded files does not equal N. Unlike slices, arrays cannot be resized, so a mismatch is fatal.","triggerScenarios":"Binding a multipart upload into a struct field typed [3]*multipart.FileHeader but the client sends 2 or 4 files under that field name; using a fixed array when the client can send a variable number of files.","commonSituations":"Hard-coding array length to a contract (e.g. \"exactly two avatar variants\") and a client sending a different count; copy-paste from a struct where N used to match.","solutions":["Switch the field to []*multipart.FileHeader so it accepts any count, then validate the length in the handler.","Keep the fixed array but enforce the expected count client-side and validate len(r.Filename) before binding.","If exactly N files are mandatory, reject the request with 400 when the file count differs rather than relying on the bind error."],"exampleFix":"// before\ntype Form struct {\n    Files [2]*multipart.FileHeader `form:\"files\"`\n}\n// after\ntype Form struct {\n    Files []*multipart.FileHeader `form:\"files\"`\n}\n// then: if len(form.Files) != 2 { c.AbortWithStatus(400) }","handlingStrategy":"validation","validationCode":"if _, fh := c.MultipartForm.File[\"files\"]; len(fh) != N {\n    c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{\"error\": fmt.Sprintf(\"exactly %d files required\", N)})\n    return\n}","typeGuard":null,"tryCatchPattern":"if err := c.ShouldBind(&form); err != nil {\n    if errors.Is(err, binding.ErrMultiFileHeaderLenInvalid) {\n        c.AbortWithStatus(http.StatusBadRequest) // wrong file count for fixed array\n        return\n    }\n}","preventionTips":["Prefer []*multipart.FileHeader slices over fixed-size arrays for uploads.","Validate the file count explicitly before relying on the bind error.","Keep the array length in a named constant shared with clients."],"tags":["binding","multipart","array","upload","go"],"analyzedSha":"34dac209ffb6ef85cc78c5d217bbb7ad001d68fd","analyzedAt":"2026-08-04T21:26:18.438Z","schemaVersion":2}