What causes "Failed to create tar header for %s: %s" in hashicorp/packer?

Identify the offending file from the error and check its type (stat )

Failed to create tar header for %s: %s

Error message

Failed to create tar header for %s: %s

What it means

tar.FileInfoHeader failed to build a tar header from a file's metadata in Packer's compress post-processor. Even with valid stat data, the tar library can reject file metadata it cannot represent (e.g. irregular file types or unsupported mode bits), aborting archive creation.

Source

Thrown at post-processor/compress/post-processor.go:395

func createTarArchive(files []string, output io.WriteCloser) error {
	archive := tar.NewWriter(output)
	defer archive.Close()

	for _, path := range files {
		file, err := os.Open(path)
		if err != nil {
			return fmt.Errorf("Unable to read file %s: %s", path, err)
		}
		defer file.Close()

		fi, err := file.Stat()
		if err != nil {
			return fmt.Errorf("Unable to get fileinfo for %s: %s", path, err)
		}

		header, err := tar.FileInfoHeader(fi, path)
		if err != nil {
			return fmt.Errorf("Failed to create tar header for %s: %s", path, err)
		}

		// workaround for archive format on go >=1.10
		setHeaderFormat(header)

		if err := archive.WriteHeader(header); err != nil {
			return fmt.Errorf("Failed to write tar header for %s: %s", path, err)
		}

		if _, err := io.Copy(archive, file); err != nil {
			return fmt.Errorf("Failed to copy %s data to archive: %s", path, err)
		}
	}
	return nil
}

func createZipArchive(files []string, output io.WriteCloser) error {
	archive := zip.NewWriter(output)

View on GitHub (pinned to eb36e3c3e4)

Solutions

Identify the offending file from the error and check its type (stat <file>)
Ensure artifacts contain only regular files; remove/replace special files upstream
Update Packer to a version with current tar-library behavior fixes
Fall back to archive = "zip" if the artifact set includes non-regular files

Defensive patterns

Strategy: validation

Validate before calling

// pre-flight: only regular files can get valid tar headers
for _, p := range artifact.Files() {
    fi, err := os.Stat(p)
    if err != nil { return err }
    if !fi.Mode().IsRegular() {
        return fmt.Errorf("%s is not a regular file (mode %s); tar cannot archive it", p, fi.Mode())
    }
}

Try / catch

// Go: detect header failure and fall back to zip (tolerates special files)
if err != nil && strings.Contains(err.Error(), "Error creating tar") &&
    strings.Contains(err.Error(), "Failed to create tar header") {
    cfg.Archive = "zip"
    return pp.PostProcess(ctx, ui, artifact)
}

Prevention

Ensure builders emit only regular files as artifacts
Filter sockets/FIFOs/devices out of the artifact before compression
Keep Packer updated for tar-library behavior changes
Test the full pipeline after changing builders that produce unusual outputs

When it happens

Trigger: createTarArchive calls tar.FileInfoHeader(fi, path) after a successful Stat and the tar package returns an error — typically for a file whose type cannot be encoded in a tar header (device files, sockets, FIFOs) or invalid metadata.

Common situations: An artifact listing a special file (socket/FIFO/device) produced by an unusual builder or plugin; very unusual file modes; Go version/library changes altering FileInfoHeader strictness.

Related errors

AI-assisted analysis of hashicorp/packer@eb36e3c3e4 (2026-09-05). Data as JSON: /api/errors/ec90b134dd928481. Report an issue: GitHub.