flipped-aurora/gin-vue-admin · error

构造 FileHeader 失败

Error message

构造 FileHeader 失败

What it means

BuildFileHeader reconstructs a *multipart.FileHeader from raw chunk bytes by building an in-memory multipart form. After parsing the form, it expects at least one file under fieldName; if the form has none, it removes temp files and returns the error "构造 FileHeader 失败". This means the constructed multipart payload did not yield a file part under the expected field name.

Source

Thrown at server/utils/upload/chunk.go:121

	part, err := mw.CreateFormFile(fieldName, fileName)
	if err != nil {
		return nil, nil, err
	}
	if _, err = io.Copy(part, src); err != nil {
		return nil, nil, err
	}
	if err = mw.Close(); err != nil {
		return nil, nil, err
	}
	reader := multipart.NewReader(body, mw.Boundary())
	form, err := reader.ReadForm(1 << 20) // 1MB 以上落临时盘,避免大文件 OOM
	if err != nil {
		return nil, nil, err
	}
	files := form.File[fieldName]
	if len(files) == 0 {
		_ = form.RemoveAll()
		return nil, nil, fmt.Errorf("构造 FileHeader 失败")
	}
	return files[0], func() { _ = form.RemoveAll() }, nil
}

View on GitHub (pinned to 3136500ef3)

Solutions

1. Ensure the fieldName argument exactly matches the form field name used to write the multipart part.
2. Verify the multipart body actually contains a file part with data before calling BuildFileHeader.
3. Check that the boundary and Content-Type used to parse the form are the ones used to write it.
4. Log len(form.File) keys after parsing to confirm which fields exist.

Example fix

// before
fh, _, err := BuildFileHeader(buf, "chunk") // written as field "file"

// after
fh, cleanup, err := BuildFileHeader(buf, "file") // matches the writer's field name

func hasFilePart(body io.Reader, boundary, fieldName string) bool {
    r := multipart.NewReader(body, boundary)
    form, err := r.ReadForm(32 << 20)
    if err != nil { return false }
    defer form.RemoveAll()
    return len(form.File[fieldName]) > 0
}

fh, cleanup, err := upload.BuildFileHeader(buf, fieldName)
if err != nil {
    defer func() { if cleanup != nil { cleanup() } }()
    return fmt.Errorf("no file part %q in constructed form: %w", fieldName, err)
}
defer cleanup()

When it happens

Trigger: Calling BuildFileHeader with a fieldName that does not match the field name used when writing the multipart body, or with empty/invalid multipart content, so form.File[fieldName] is empty after parsing.

Common situations: Field name mismatch between chunk writer and reader (e.g. "file" vs "chunk"); mime/multipart form written without the file part; empty chunk data producing no part; incorrect boundary/Content-Type passed to the form parser.

Related errors

• function file.Open() failed, err:
• function file.Open() failed, err:
• function file.Open() failed, err:
• function file.Open() failed, err:
• 缺少分片 %d: %w

AI-assisted analysis of flipped-aurora/gin-vue-admin@3136500ef3 (2026-08-31). Data as JSON: /api/errors/cbd9f6e3e40b0259. Report an issue: GitHub.