gofiber/fiber · error · ErrFileHeaderNil

file: file header is nil

Error message

file: file header is nil

What it means

ErrFileHeaderNil (error.go:97) is returned by ctx.SaveFile (ctx.go:559) and ctx.SaveFileToStorage (ctx.go:567) when the supplied *multipart.FileHeader is nil. Both methods dereference the header (for filename, Open(), Size), so a nil guard runs first and returns this sentinel instead of panicking on a nil pointer dereference.

Source

Thrown at error.go:97

	// SyntaxError is a description of a JSON syntax error.
	SyntaxError = json.SyntaxError

	// UnmarshalTypeError describes a JSON value that was
	// not appropriate for a value of a specific Go type.
	UnmarshalTypeError = json.UnmarshalTypeError

	// UnsupportedTypeError is returned by Marshal when attempting
	// to encode an unsupported value type.
	UnsupportedTypeError = json.UnsupportedTypeError

	// UnsupportedValueError exposes json.UnsupportedValueError to describe unsupported values encountered during encoding.
	UnsupportedValueError = json.UnsupportedValueError
)

// File errors
var (
	ErrFileHeaderNil = errors.New("file: file header is nil")
	ErrFileOpen      = errors.New("file: failed to open file")
	ErrFileRead      = errors.New("file: failed to read file")
	ErrFileStore     = errors.New("file: failed to store file")
)

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Check that the file header is non-nil and that c.FormFile returned no error before saving.
2. Validate file presence and return a 400 to the client when the upload field is missing.
3. Guard the save call: if fileheader == nil { return fiber.NewError(fiber.StatusBadRequest, "file required") }.

Example fix

// before
fh, _ := c.FormFile("upload")
c.SaveFile(fh, "./uploads/"+fh.Filename) // panics if fh is nil

// after
fh, err := c.FormFile("upload")
if err != nil {
    return fiber.NewError(fiber.StatusBadRequest, "upload field required")
}
return c.SaveFile(fh, "./uploads/"+fh.Filename)

// Confirm the file part exists before saving.
fh, err := c.FormFile("upload")
if err != nil || fh == nil {
    return fiber.NewError(fiber.StatusBadRequest, "upload file required")
}
return c.SaveFile(fh, dest)

// narrow a possibly-nil header before dereferencing
func validHeader(fh *multipart.FileHeader) (*multipart.FileHeader, error) {
    if fh == nil {
        return nil, fiber.ErrFileHeaderNil
    }
    return fh, nil
}

if err := c.SaveFile(fh, dest); err != nil {
    if errors.Is(err, fiber.ErrFileHeaderNil) {
        return fiber.NewError(fiber.StatusBadRequest, "no file provided")
    }
    return err
}

When it happens

Trigger: Calling c.SaveFile(nil, path), or passing a FileHeader obtained from c.FormFile("field") when the field was absent (and the caller didn't check the error), then forwarding that nil header to SaveFile. Also when looping over an empty file slice and dereferencing.

Common situations: Upload handlers that assume a file is always present, form fields renamed client-side, or multipart parsing that returns a nil header on missing parts.

Related errors

• file: failed to read file
• file: failed to store file
• failed to close multipart writer: %w
• write formdata error: %w
• create file error: %w

AI-assisted analysis of gofiber/fiber@9a4c7e57fe (2026-08-04). Data as JSON: /data/errors/010f7c2657193c57.json. Report an issue: GitHub.