gofiber/fiber · error

the file should have a name

Error message

the file should have a name

What it means

Returned by writeMultipartBody (client/hooks.go:280) when iterating req.files and encountering a File whose Name and Path are both empty. The multipart writer needs at least one identifier to emit a Content-Disposition file part, so an empty File is rejected rather than silently dropped.

Solutions

1. Ensure every File in req.files has either Name or Path set before Send().
2. Filter empty entries out of the slice before passing it: slices.DeleteFunc(files, func(f File) bool { return f.Name == "" && f.Path == "" }).
3. When uploading from disk, set Path so the binder derives Name from filepath.Base(Path) (see hooks.go:284-287).
4. Validate the files slice in a helper before sending.

Example fix

// before
req.File(fiber.File{FieldName: "upload"}) // no Name or Path -> ErrFileNoName

// after
req.File(fiber.File{FieldName: "upload", Name: "report.csv", Body: data})

func sanitizeFiles(files []fiber.File) []fiber.File {
    return slices.DeleteFunc(files, func(f fiber.File) bool {
        return f.Name == "" && f.Path == ""
    })
}

func hasNameOrPath(f fiber.File) bool { return f.Name != "" || f.Path != "" }

if err := req.Send(); err != nil {
    if errors.Is(err, fiber.ErrFileNoName) {
        // filter the files slice and retry
    }
}

When it happens

Trigger: Calling req.File(...) with an empty fiber.File{}; pushing a File where only FieldName was set; building the files slice programmatically and leaving Name/Path blank for one element; calling req.Files([]File{{FieldName: "upload"}}).

Common situations: Appending zero-value File structs from a loop that didn't populate fields; receiving file metadata from an upstream that omitted the filename; refactoring that swaps field order and leaves Name unset.

Related errors

• boundary generation
• failed to close multipart writer
• only file paths and io.Writer are supported
• set boundary error
• write formdata error

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

Appendix: source

Thrown at client/core.go:303

// releaseErrChan returns the error channel to the pool.
// It's caller's responsibility to ensure that:
// - the channel is not closed
// - the channel is drained before returning it
// - the channel is not reused after returning it
func releaseErrChan(ch chan error) {
	errChanPool.Put(ch)
}

// newCore returns a new core object.
func newCore() *core {
	return &core{}
}

var (
	ErrTimeoutOrCancel      = errors.New("timeout or cancel")
	ErrURLFormat            = errors.New("the URL is incorrect")
	ErrNotSupportSchema     = errors.New("protocol not supported; only http or https are allowed")
	ErrFileNoName           = errors.New("the file should have a name")
	ErrBodyType             = errors.New("the body type should be []byte")
	ErrNotSupportSaveMethod = errors.New("only file paths and io.Writer are supported")
	ErrBodyTypeNotSupported = errors.New("the body type is not supported")
)

View on GitHub (pinned to a105acad6c)