gofiber/fiber · error · ErrFileRead

file: failed to read file

Error message

file: failed to read file

What it means

ErrFileRead ('file: failed to read file', error.go:99) is wrapped and returned by ctx.SaveFileToStorage (ctx.go:582,590,594) when reading the uploaded multipart file fails. Three sub-causes: the file's declared Size exceeds app.Config.BodyLimit (ctx.go:582), the actual bytes read exceed the limit (ctx.go:594, wrapping fasthttp.ErrBodyTooLarge), or the underlying reader errors mid-stream (ctx.go:590). The error is wrapped with the filename for diagnosis.

Source

Thrown at error.go:98

	// 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. Raise app.Config.BodyLimit (or the per-route body limit) to exceed your maximum expected upload size.
2. Check the wrapped error (errors.Is(err, fasthttp.ErrBodyTooLarge)) to distinguish size rejection from I/O failure.
3. Validate Content-Length against your limit early and reject with 413 before streaming.

Example fix

// before
app := fiber.New() // default BodyLimit too small for video

// after
app := fiber.New(fiber.Config{BodyLimit: 50 * 1024 * 1024}) // 50 MB
app.Post("/upload", func(c fiber.Ctx) error {
    fh, err := c.FormFile("video")
    if err != nil {
        return fiber.NewError(fiber.StatusBadRequest, err.Error())
    }
    if err := c.SaveFileToStorage(fh, fh.Filename, storage); err != nil {
        if errors.Is(err, fiber.ErrFileRead) {
            return fiber.NewError(fiber.StatusRequestEntityTooLarge, "upload too large")
        }
        return err
    }
    return c.SendStatus(200)
})

// Reject oversized uploads before streaming to storage.
if fh, _ := c.FormFile("file"); fh != nil && fh.Size > int64(maxUpload) {
    return fiber.NewError(fiber.StatusRequestEntityTooLarge, "file too large")
}

if err := c.SaveFileToStorage(fh, key, storage); err != nil {
    if errors.Is(err, fiber.ErrFileRead) {
        if errors.Is(err, fasthttp.ErrBodyTooLarge) {
            return fiber.NewError(fiber.StatusRequestEntityTooLarge, "upload exceeds body limit")
        }
        return fiber.NewError(fiber.StatusBadRequest, "failed reading upload")
    }
    return err
}

When it happens

Trigger: An upload larger than BodyLimit (default or configured) passed to SaveFileToStorage; a network interruption truncating the multipart body; or a corrupt file header reporting an inconsistent size. Triggered by c.SaveFileToStorage(fh, key, storage) under those conditions.

Common situations: Default BodyLimit too small for legitimate uploads, reverse proxies with their own body limits truncating requests, or storage backends reporting read faults. Increasing upload size without raising BodyLimit is the classic mismatch.

Related errors

• file: file header is nil
• file: failed to store file
• file: failed to read file: %q: %w
• failed to close multipart writer: %w
• write formdata error: %w

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