gofiber/fiber · error

write formdata error: %w

Error message

write formdata error: %w

What it means

Returned in writeMultipartBody (client/hooks.go:267) when multipart.Writer.WriteField fails for any form-field entry. WriteField writes a part header and value into the request body writer; a failure means the underlying writer rejected the write (buffer cap, transport error, or an excessively long field that overflows the request buffer).

Source

Thrown at client/hooks.go:267

	if err := mw.Close(); err != nil {
		return fmt.Errorf("failed to close multipart writer: %w", err)
	}

	return nil
}

// writeMultipartBody writes the form fields and files of req to mw.
func writeMultipartBody(mw *multipart.Writer, req *Request) error {
	// Add form data.
	var err error
	for key, value := range req.formData.All() {
		err = mw.WriteField(utils.UnsafeString(key), utils.UnsafeString(value))
		if err != nil {
			break
		}
	}
	if err != nil {
		return fmt.Errorf("write formdata error: %w", err)
	}

	// Add files.
	fileBuf, ok := fileBufPool.Get().(*[]byte)
	if !ok {
		return errSyncPoolBuffer
	}

	defer fileBufPool.Put(fileBuf)

	for i, f := range req.files {
		if f.name == "" && f.path == "" {
			return ErrFileNoName
		}

		// Set the file name if not provided.
		if f.name == "" && f.path != "" {
			f.path = filepath.Clean(f.path)

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Move large payloads from form fields into file parts (SetFiles) which stream through a 1MB copy buffer.
2. Reduce the number/size of form fields or chunk the upload.
3. Ensure the Request is not concurrently released while the body is being written.
4. Check the wrapped error for buffer-size vs. connection-failure semantics.

Example fix

// before — huge value crammed into a form field
req.SetFormData(map[string]string{"blob": hugeBase64})

// after — send large data as a file part instead
req.SetFileReader("blob", "blob.bin", bytes.NewReader(blobBytes))

// Reject oversized form-field payloads before sending.
const maxFieldBytes = 1 << 20 // 1 MiB
func fieldsFit(fields map[string]string) bool {
    var n int
    for k, v := range fields { n += len(k) + len(v) }
    return n <= maxFieldBytes
}

if err := sendMultipart(req); err != nil && strings.Contains(err.Error(), "write formdata error") {
    // move large fields into file parts and retry
}

When it happens

Trigger: Adding many or very large form fields via Request.SetFormData/SetParam and sending a filesBody request, where the accumulated form-field data exceeds the request body buffer or the body writer errors. Also possible if a field value contains data that breaks the writer.

Common situations: Base64-encoding a large blob into a form field; thousands of form fields; a body-stream target already closed; concurrent reuse of the Request object; a server/proxy enforcing a smaller body limit that surfaces client-side.

Related errors

• failed to close multipart writer: %w
• create file error: %w
• file: file header is nil
• file: failed to read file
• rand.Read failed: %w

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