gofiber/fiber · error

file: file header is nil

Error message

file: file header is nil

What it means

ErrFileHeaderNil is returned by DefaultCtx.SaveFile (ctx.go:559) and DefaultCtx.SaveFileToStorage (ctx.go:567) when the caller passes a nil *multipart.FileHeader. The methods need a non-nil header to open the underlying multipart part; nil short-circuits before any filesystem operation.

Solutions

1. Check the error from c.FormFile before calling SaveFile: fh, err := c.FormFile("file"); if err != nil { return err }.
2. Before iterating multipart files, confirm c.MultipartForm() is non-nil and the target key exists.
3. Add an explicit nil check on the header so the failure points at your code rather than the library.

Example fix

// before
fh, _ := c.FormFile("file")
return c.SaveFile(fh, "./uploads/"+fh.Filename)
// after
fh, err := c.FormFile("file")
if err != nil {
    return err
}
return c.SaveFile(fh, "./uploads/"+fh.Filename)

// Always check FormFile's error before touching the header.
fh, err := c.FormFile("file")
if err != nil {
    return c.Status(fiber.StatusBadRequest).SendString("file required")
}
if fh == nil {
    return c.Status(fiber.StatusBadRequest).SendString("file header missing")
}
return c.SaveFile(fh, "./uploads/"+fh.Filename)

if err := c.SaveFile(fh, path); err != nil {
    if errors.Is(err, fiber.ErrFileHeaderNil) {
        return c.Status(fiber.StatusBadRequest).SendString("no file uploaded")
    }
    return err
}

When it happens

Trigger: Passing a nil pointer to c.SaveFile(fh, path) or c.SaveFileToStorage(fh, path, storage). Common when c.FormFile(field) returned an error that was ignored and the header was never assigned, or when iterating a missing multipart form.

Common situations: Ignoring the error from c.FormFile and using the zero-value *multipart.FileHeader; uploading without enctype=multipart/form-data so the form is empty; iterating c.MultipartForm().File and dereferencing absent keys.

Related errors

• file: failed to open file
• set boundary error
• boundary generation
• failed to close multipart writer
• file: failed to read file

AI-assisted analysis of gofiber/fiber@a105acad6c (2026-08-11). Data as JSON: /api/errors/010f7c2657193c57. Report an issue: GitHub.

Appendix: source

Thrown at error.go:102

	// 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 a105acad6c)