valyala/fasthttp · error

error when marshaling multipart form

Error message

error when marshaling multipart form: %w

What it means

When writing a request that consists only of a multipart form, fasthttp marshals the form into the body; this error wraps any failure from that marshaling (part creation, file copy/close, writer close — i.e. errors 170-173 bubbling up). The request cannot be serialized and is not sent.

Solutions

1. Unwrap the cause to find the specific part that failed (field name is embedded).
2. Ensure source files/readers are valid at client.Do time.
3. Reset the Request before each reuse.
4. Wrap client.Do in error handling that distinguishes request-build errors from network errors.

Example fix

// before
err := client.Do(req, resp) // generic handling
// after
if err := client.Do(req, resp); err != nil {
    var be *fasthttp.ErrSmallBuffer // example typed handling
    log.Printf("request build/send failed: %v", err)
    req.Reset()
}

for k, fhs := range req.MultipartForm.File {
    for _, fh := range fhs {
        if fh == nil { return fmt.Errorf("nil file header for %s", k) }
    }
}

func isRequestBuildError(err error) bool {
    msg := err.Error()
    return strings.Contains(msg, "multipart form") ||
        strings.Contains(msg, "form file")
}

if err := client.Do(req, resp); err != nil {
    if strings.Contains(err.Error(), "error when marshaling multipart form") {
        req.Reset()
        return fmt.Errorf("rebuild upload request: %w", err)
    }
    return err
}

When it happens

Trigger: client.Do / Request.Write with req.onlyMultipartForm() true (set via SetFormFile* APIs) when marshalMultipartForm fails for any of the underlying part-write reasons.

Common situations: Upload of a file that disappeared between SetFormFileCreate and Do; reusing a Request without Reset; failing custom readers in the multipart form.

Related errors

• cannot close form file
• cannot open form file
• error when closing multipart form writer
• error when copying form file
• fasthttp: request content-type has bad boundary or is not…

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

Appendix: source

Thrown at http.go:1845

			buf = append(buf, uri.username...)
			buf = append(buf, strColon...)
			buf = append(buf, uri.password...)
			buf = append(buf, strBasicSpace...)
			base64.StdEncoding.Encode(buf[nb:tl], buf[:nl])
			req.Header.SetBytesKV(strAuthorization, buf[nl:tl])
		}
	}

	if req.bodyStream != nil {
		return req.writeBodyStream(w)
	}

	body := req.bodyBytes()
	var err error
	if req.onlyMultipartForm() {
		body, err = marshalMultipartForm(req.multipartForm, req.multipartFormBoundary)
		if err != nil {
			return fmt.Errorf("error when marshaling multipart form: %w", err)
		}
		req.Header.SetMultipartFormBoundary(req.multipartFormBoundary)
	}

	hasBody := false
	if len(body) == 0 {
		body = req.postArgs.QueryString()
	}
	if len(body) != 0 || !req.Header.ignoreBody() {
		hasBody = true
		req.Header.SetContentLength(len(body))
	}
	if err = req.Header.Write(w); err != nil {
		return err
	}
	if hasBody {
		_, err = w.Write(body)
	} else if len(body) > 0 {

View on GitHub (pinned to c96f600972)