What causes "error inspecting next tar header" in hyperledger/fabric?

Repackage the chaincode with 'peer lifecycle chaincode package'.

error inspecting next tar header

Error message

error inspecting next tar header

What it means

This error is returned when tarReader.Next() fails mid-iteration while searching a package tar for the named entry. gzip decompression succeeded, but the tar payload is malformed — bad header checksum, truncated archive, or corrupt entries. It wraps the underlying tar error for the File helper shared by Metadata, MetadataBytes, and Code.

Source

Thrown at core/chaincode/persistence/chaincode_package.go:186

			file.Close()
		}
	}()

	gzReader, err := gzip.NewReader(file)
	if err != nil {
		return nil, errors.Wrapf(err, "error reading as gzip stream")
	}

	tarReader := tar.NewReader(gzReader)

	for {
		header, err := tarReader.Next()
		if err == io.EOF {
			break
		}

		if err != nil {
			return nil, errors.Wrapf(err, "error inspecting next tar header")
		}

		if header.Name != name {
			continue
		}

		if header.Typeflag != tar.TypeReg {
			return nil, errors.Errorf("tar entry %s is not a regular file, type %v", header.Name, header.Typeflag)
		}

		return &TarFileStream{
			TarFile:    tarReader,
			FileStream: file,
		}, nil
	}

	return nil, errors.Errorf("did not find file '%s' in package", name)
}

View on GitHub (pinned to 2736b63f8f)

Solutions

Repackage the chaincode with 'peer lifecycle chaincode package'.
Test archive integrity: tar -tzvf <package> should list all entries without errors.
Verify the file wasn't truncated (compare size/checksum with the source).
Avoid re-saving or post-processing the package with editors or text-mode transfers.

Example fix

// before: re-zipping a partially extracted package
zip corrupt-pkg.tgz *.json
// after: recreate from source artifacts
peer lifecycle chaincode package mycc.tgz --path ./src --lang golang --label mycc-v1

Defensive patterns

Strategy: validation

Validate before calling

f, err := os.Open(pkgPath)
if err != nil { return err }
gr, err := gzip.NewReader(f)
if err != nil { return fmt.Errorf("not gzip: %w", err) }
tr := tar.NewReader(gr)
for {
	if _, err := tr.Next(); err == io.EOF { break } else if err != nil {
		return fmt.Errorf("package %s has corrupt tar: %w", pkgPath, err)
	}
}

Try / catch

meta, err := p.Metadata(pkgPath)
if err != nil {
	if strings.Contains(err.Error(), "error inspecting next tar header") {
		return fmt.Errorf("package %s corrupt, repackage it", pkgPath)
	}
	return err
}

Prevention

Validate packages with 'tar -tzvf' immediately after creation.
Never post-edit or re-save package files.
Check disk space and transfer completion before installing.
Keep package files binary-safe end to end.

When it happens

Trigger: Calling Metadata(), MetadataBytes(), or Code() on a file whose gzip layer decompresses but whose tar structure is corrupt or truncated before a valid EOF.

Common situations: Partial downloads, disks filling mid-write during packaging, archives edited/re-zipped by non-tar tools, or transmission modes (e.g. ASCII ftp) corrupting binary data.

Related errors

AI-assisted analysis of hyperledger/fabric@2736b63f8f (2026-09-04). Data as JSON: /api/errors/d486fee047e94f3d. Report an issue: GitHub.