vxcontrol/pentagi · error

tar archive header generation failed: %w

Error message

tar archive header generation failed: %w

What it means

writeFileToContainer builds an in-memory tar archive before copying the file into the flow's Docker container. This error wraps archiveWriter.WriteHeader failing while emitting the tar.Header for the target file (name=basename, mode 0600, size=len(content)). WriteHeader only fails on programmer-level problems: a nil/invalid header, a negative or unset Size, or an I/O error on the underlying buffer, so it is rare in practice.

Source

Thrown at backend/pkg/tools/terminal.go:474

	}
	if !isRunning {
		return fmt.Errorf("target container is not operational")
	}

	// Docker SDK requires TAR format for file transfer
	tarBuffer := &bytes.Buffer{}
	archiveWriter := tar.NewWriter(tarBuffer)
	defer archiveWriter.Close()

	filename := filepath.Base(path)
	fileDescriptor := &tar.Header{
		Name: filename,
		Mode: 0600,
		Size: int64(len(content)),
	}
	err = archiveWriter.WriteHeader(fileDescriptor)
	if err != nil {
		return fmt.Errorf("tar archive header generation failed: %w", err)
	}

	_, err = archiveWriter.Write([]byte(content))
	if err != nil {
		return fmt.Errorf("tar archive content serialization failed: %w", err)
	}

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

	dir := filepath.Dir(path)
	err = t.dockerClient.CopyToContainer(ctx, containerName, dir, tarBuffer, client.CopyToContainerOptions{
		AllowOverwriteDirWithFile: true,
	})
	if err != nil {
		return fmt.Errorf("container file transfer failed: %w", err)

View on GitHub (pinned to ea665308ba)

Solutions

1. Check host/container memory pressure; retry the WriteFile/EditFile tool call once memory is available
2. Verify content length is a sane non-negative size and retry the operation
3. If reproducible, capture the wrapped error (%w cause) and report it — a failing WriteHeader into a bytes.Buffer usually indicates an SDK/library version issue
4. Pin/upgrade github.com/archive/tar (stdlib) and the Docker SDK to compatible versions and rebuild the backend

Example fix

// before
fileDescriptor := &tar.Header{Name: filename, Mode: 0600, Size: int64(len(content))}
if err := archiveWriter.WriteHeader(fileDescriptor); err != nil {
    return fmt.Errorf("tar archive header generation failed: %w", err)
}
// after
if len(content) < 0 { // defensive guard
    return fmt.Errorf("content size must be non-negative, got %d", len(content))
}
fileDescriptor := &tar.Header{Name: filename, Mode: 0600, Size: int64(len(content))}
if err := archiveWriter.WriteHeader(fileDescriptor); err != nil {
    return fmt.Errorf("tar archive header generation failed: %w", err)
}

if len(content) > 64<<20 {
    return fmt.Errorf("refusing to write %d bytes: too large", len(content))
}

if _, err := term.WriteFile(ctx, flowID, content, path); err != nil {
    if strings.Contains(err.Error(), "tar archive header generation failed") {
        // log wrapped cause via errors.Unwrap and retry once
    }
}

When it happens

Trigger: Calling WriteFile or EditFile when the tar.Header passed to WriteHeader is invalid (e.g. Size would be negative because content length overflows int, or the header struct is malformed); the bytes.Buffer backing the tar writer returns an I/O error (only possible with an out-of-memory condition).

Common situations: Practically only seen with extremely large or corrupted content buffers causing memory allocation failure; a plain memory-constrained host (OOM pressure) during agent file-write operations; virtually never from bad user input.

Related errors

• tar archive content serialization failed: %w
• failed to close tar writer: %w
• failed to copy file: %w
• failed to read tar header: %w
• file '%s' has invalid size %d

AI-assisted analysis of vxcontrol/pentagi@ea665308ba (2026-09-01). Data as JSON: /api/errors/eedce09741a482ba. Report an issue: GitHub.