gin-gonic/gin · error · ErrMultiFileHeader

unsupported field type for multipart.FileHeader

Error message

unsupported field type for multipart.FileHeader

What it means

ErrMultiFileHeader is returned by setByMultipartFormFile (binding/multipart_form_mapping.go:60) when a multipart upload field maps to a struct field whose type is not one Gin's file binder recognises. Recognised types are *multipart.FileHeader, multipart.FileHeader, []multipart.FileHeader, []*multipart.FileHeader, [N]multipart.FileHeader, [N]*multipart.FileHeader.

Source

Thrown at binding/multipart_form_mapping.go:20

// Use of this source code is governed by a MIT style
// license that can be found in the LICENSE file.

package binding

import (
	"errors"
	"mime/multipart"
	"net/http"
	"reflect"
)

type multipartRequest http.Request

var _ setter = (*multipartRequest)(nil)

var (
	// ErrMultiFileHeader multipart.FileHeader invalid
	ErrMultiFileHeader = errors.New("unsupported field type for multipart.FileHeader")

	// ErrMultiFileHeaderLenInvalid array for []*multipart.FileHeader len invalid
	ErrMultiFileHeaderLenInvalid = errors.New("unsupported len of array for []*multipart.FileHeader")
)

// TrySet tries to set a value by the multipart request with the binding a form file
func (r *multipartRequest) TrySet(value reflect.Value, field reflect.StructField, key string, opt setOptions) (bool, error) {
	if files := r.MultipartForm.File[key]; len(files) != 0 {
		return setByMultipartFormFile(value, field, files)
	}

	return setByForm(value, field, r.MultipartForm.Value, key, opt)
}

func setByMultipartFormFile(value reflect.Value, field reflect.StructField, files []*multipart.FileHeader) (isSet bool, err error) {
	switch value.Kind() {
	case reflect.Ptr:
		switch value.Interface().(type) {

View on GitHub (pinned to 34dac209ff)

Solutions

Declare the field as *multipart.FileHeader (single file) or []*multipart.FileHeader (multiple).
Open the file via header.Open() inside the handler if you need an io.Reader.
If you need only the filename/size, read it off the *multipart.FileHeader after binding.

Example fix

// before
type Upload struct {
    File io.Reader `form:"file"`
}
// after
type Upload struct {
    File *multipart.FileHeader `form:"file"`
}
// then in handler: src, _ := form.File.Open(); defer src.Close()

Defensive patterns

Strategy: type-guard

Validate before calling

func isFileHeaderField(t reflect.Type) bool {
    switch t {
    case reflect.TypeOf(&multipart.FileHeader{}), reflect.TypeOf(multipart.FileHeader{}):
        return true
    }
    if t.Kind() == reflect.Slice {
        elem := t.Elem()
        return elem == reflect.TypeOf(&multipart.FileHeader{}) || elem == reflect.TypeOf(multipart.FileHeader{})
    }
    if t.Kind() == reflect.Array {
        elem := t.Elem()
        return elem == reflect.TypeOf(&multipart.FileHeader{}) || elem == reflect.TypeOf(multipart.FileHeader{})
    }
    return false
}

Type guard

var _ *multipart.FileHeader = (*multipart.FileHeader)(nil)

Try / catch

if err := c.ShouldBind(&form); err != nil {
    if errors.Is(err, binding.ErrMultiFileHeader) {
        c.AbortWithStatus(http.StatusBadRequest) // wrong field type for file
        return
    }
}

Prevention

Always type file fields as *multipart.FileHeader or []*multipart.FileHeader.
Open the file with header.Open() — Gin does not give you an io.Reader directly.
Document expected field types next to the upload handler.

When it happens

Trigger: A multipart/form-data POST bound to a struct whose corresponding field is typed *os.File, io.Reader, string, []byte, or any custom struct — the file binder hits the default branch and returns this error.

Common situations: Expecting Gin to give you an open io.Reader or *os.File; typing the field as string expecting the filename; using a custom File wrapper struct instead of multipart.FileHeader.

Related errors

AI-assisted analysis of gin-gonic/gin@34dac209ff (2026-08-04). Data as JSON: /data/errors/23184fe53c514092.json. Report an issue: GitHub.