What causes "error reading as gzip stream" in hyperledger/fabric?

Re-create the package using the fabric tooling (peer lifecycle chaincode package) which always produces gzip'd tars.

error reading as gzip stream

Error message

error reading as gzip stream

What it means

This error wraps the failure of gzip.NewReader when the code (Metadata/MetadataBytes/Code) tries to open a chaincode package file as a gzip stream. It means the file on disk is not a valid gzip archive (bad magic bytes, truncated, or empty). The library requires all chaincode packages to be gzipped tar archives, so a non-gzip file is rejected at the first read.

Source

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

	return tarFileStream, nil
}

func (cps *ChaincodePackageStreamer) File(name string) (tarFileStream *TarFileStream, err error) {
	file, err := os.Open(cps.PackagePath)
	if err != nil {
		return nil, errors.WithMessagef(err, "could not open chaincode package at '%s'", cps.PackagePath)
	}

	defer func() {
		if err != nil {
			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
		}

View on GitHub (pinned to 2736b63f8f)

Solutions

Re-create the package using the fabric tooling (peer lifecycle chaincode package) which always produces gzip'd tars.
Verify the file starts with the gzip magic bytes (1f 8b): file <packagepath> or head -c2 | xxd.
Check file size and integrity (cmp against original, re-download/copy).
Ensure you are pointing Metadata/Code at the packaged .tar.gz file, not the extracted source directory.

Example fix

// before: passing a plain tar produced manually
tar -cf mycc.tar metadata.json code.tar
// after: gzip the tar so gzip.NewReader succeeds
tar -czf mycc.tgz metadata.json code.tar

Defensive patterns

Strategy: validation

Validate before calling

func looksGzip(path string) bool {
	f, err := os.Open(path)
	if err != nil { return false }
	defer f.Close()
	magic := make([]byte, 2)
	if _, err := io.ReadFull(f, magic); err != nil { return false }
	return magic[0] == 0x1f && magic[1] == 0x8b
}
if !looksGzip(pkgPath) { return fmt.Errorf("%s is not a gzip archive", pkgPath) }

Type guard

func isGzipBytes(b []byte) bool { return len(b) >= 2 && b[0] == 0x1f && b[1] == 0x8b }

Try / catch

file, err := os.Open(pkgPath)
if err != nil { return err }
meta, err := p.Metadata(pkgPath)
if err != nil {
	var wrapped interface{ Unwrap() error }
	if errors.As(err, &target) { log.Fatalf("not gzip: %v", err) }
	return err
}

Prevention

Always package with 'peer lifecycle chaincode package', never plain tar.
Checksum packages after creation and before use.
Verify gzip magic bytes before calling Metadata/Code.
Use binary-safe transfers (no ASCII ftp/text mode).

When it happens

Trigger: Calling Metadata(), MetadataBytes(), or Code() on a File whose underlying path contains bytes that fail gzip header validation — e.g. a plain (uncompressed) tar, a raw binary, or a zero-byte file.

Common situations: A user packaged chaincode without gzip compression, a download/copy was truncated or corrupted, an empty placeholder file was created, or an old/non-standard packaging tool produced a plain tar.

Related errors

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