valyala/fasthttp · error

error when marshaling multipart form: %w

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.

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)

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

• fasthttp: request content-type has bad boundary or is not mu
• form boundary cannot be empty
• fasthttp: there is no uploaded file associated with the give
• cannot open form file %q (%q): %w
• error when copying form file %q (%q): %w

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