What causes "form boundary cannot be empty" in valyala/fasthttp?

Pass a non-empty boundary, e.g. one generated with multipart.NewWriter(...).Boundary() or random.Boundary().

form boundary cannot be empty

Error message

form boundary cannot be empty

What it means

WriteMultipartForm serializes a multipart.Form to a writer using the supplied boundary string. An empty boundary is invalid — multipart.NewWriter.SetBoundary would reject it — so the function fails fast with this error before writing anything.

Source

Thrown at http.go:1225

	return req.multipartForm, nil
}

func marshalMultipartForm(f *multipart.Form, boundary string) ([]byte, error) {
	var buf bytebufferpool.ByteBuffer
	if err := WriteMultipartForm(&buf, f, boundary); err != nil {
		return nil, err
	}
	return buf.B, nil
}

// WriteMultipartForm writes the given multipart form f with the given
// boundary to w.
func WriteMultipartForm(w io.Writer, f *multipart.Form, boundary string) error {
	// Do not care about memory allocations here, since multipart
	// form processing is slow.
	if boundary == "" {
		return errors.New("form boundary cannot be empty")
	}

	mw := multipart.NewWriter(w)
	if err := mw.SetBoundary(boundary); err != nil {
		return fmt.Errorf("cannot use form boundary %q: %w", boundary, err)
	}

	// marshal values
	for k, vv := range f.Value {
		for _, v := range vv {
			if err := mw.WriteField(k, v); err != nil {
				return fmt.Errorf("cannot write form field %q value %q: %w", k, v, err)
			}
		}
	}

	// marshal files
	for k, fvv := range f.File {

View on GitHub (pinned to c96f600972)

Solutions

Pass a non-empty boundary, e.g. one generated with multipart.NewWriter(...).Boundary() or random.Boundary().
Extract the boundary with mime.ParseMediaType from the incoming Content-Type and validate it's non-empty before calling.
If re-emitting a parsed form, create a fresh multipart.Writer and use its boundary.
Wrap the call and return 400/500 with a clear message when the boundary is missing.

Example fix

// before
err := fasthttp.WriteMultipartForm(w, form, boundaryFromHeader) // ""
// after
mw := multipart.NewWriter(io.Discard)
boundary := mw.Boundary() // non-empty random boundary
err := fasthttp.WriteMultipartForm(w, form, boundary)

Defensive patterns

Strategy: validation

Validate before calling

if boundary == "" {
    return errors.New("multipart boundary required")
}
// or generate one:
// b := multipart.NewWriter(io.Discard).Boundary()

Try / catch

if err := fasthttp.WriteMultipartForm(w, form, boundary); err != nil {
    // regenerate a random boundary and retry once
}

Prevention

Never pass a boundary extracted from a header without checking it's non-empty
Generate boundaries with multipart.NewWriter().Boundary()
Validate with mime.ParseMediaType when reusing inbound boundaries

When it happens

Trigger: Calling fasthttp.WriteMultipartForm(w, form, "") with an empty boundary, typically when the boundary was taken from a request Content-Type that had none, or an unset variable.

Common situations: Proxying/rewriting multipart bodies after extracting a boundary from a Content-Type header that lacked one; generating responses from parsed forms where the original boundary was lost.

Related errors

AI-assisted analysis of valyala/fasthttp@c96f600972 (2026-08-31). Data as JSON: /api/errors/8b2d4c1d067f0874. Report an issue: GitHub.