What causes "error writing package metadata to tar" in hyperledger/fabric?

Read the wrapped inner error in the message to find the root cause.

error writing package metadata to tar

Error message

error writing package metadata to tar

What it means

Inside getTarGzBytes, after metadata.json is generated, writeBytesToPackage writes it into the tar stream. If that write fails (tar writer in error state, gzip/buffer failure) the error is wrapped with 'error writing package metadata to tar'. The underlying cause is always available in the wrapped message.

Source

Thrown at internal/peer/lifecycle/chaincode/package.go:171

	return nil
}

func (p *Packager) getTarGzBytes() ([]byte, error) {
	payload := bytes.NewBuffer(nil)
	gw := gzip.NewWriter(payload)
	tw := tar.NewWriter(gw)

	normalizedPath, err := p.PlatformRegistry.NormalizePath(strings.ToUpper(p.Input.Type), p.Input.Path)
	if err != nil {
		return nil, errors.WithMessage(err, "failed to normalize chaincode path")
	}
	metadataBytes, err := toJSON(normalizedPath, p.Input.Type, p.Input.Label)
	if err != nil {
		return nil, err
	}
	err = writeBytesToPackage(tw, "metadata.json", metadataBytes)
	if err != nil {
		return nil, errors.Wrap(err, "error writing package metadata to tar")
	}

	codeBytes, err := p.PlatformRegistry.GetDeploymentPayload(strings.ToUpper(p.Input.Type), p.Input.Path)
	if err != nil {
		return nil, errors.WithMessage(err, "error getting chaincode bytes")
	}

	codePackageName := "code.tar.gz"

	err = writeBytesToPackage(tw, codePackageName, codeBytes)
	if err != nil {
		return nil, errors.Wrap(err, "error writing package code bytes to tar")
	}

	err = tw.Close()
	if err == nil {
		err = gw.Close()
	}

View on GitHub (pinned to 2736b63f8f)

Solutions

Read the wrapped inner error in the message to find the root cause.
Retry the package command; transient memory pressure is the most plausible trigger.
Check available memory (free -m) and reduce concurrent peer CLI operations.
Confirm the fabric binary matches your fabric release to rule out mismatched internal writer code.

Example fix

// before: opaque handling
err := writeBytesToPackage(tw, "metadata.json", metadataBytes)
if err != nil {
    return nil, errors.Wrap(err, "error writing package metadata to tar")
}
// after: fail fast before tar writing if metadata is empty
if len(metadataBytes) == 0 {
    return nil, errors.New("empty metadata for chaincode package")
}
err := writeBytesToPackage(tw, "metadata.json", metadataBytes)
if err != nil {
    return nil, errors.Wrap(err, "error writing package metadata to tar")
}

Defensive patterns

Strategy: try-catch

Try / catch

// Go caller of getTarGzBytes-equivalent
pkgBytes, err := getTarGzBytes()
if err != nil {
    if strings.Contains(err.Error(), "error writing package metadata to tar") {
        logger.Errorf("metadata tar write failed: %v", err) // inspect wrapped cause
    }
    return fmt.Errorf("package failed: %w", err)
}

Prevention

Read the wrapped inner error; the root cause follows the message colon.
Retry once — these are typically transient memory issues.
Avoid packaging very large payloads on memory-constrained hosts.
Keep peer binaries consistent with your fabric version.

When it happens

Trigger: Failure of toJSON producing metadata, or the tar.Writer rejecting the header/bytes for metadata.json — e.g. an I/O error on the underlying bytes.Buffer or an earlier write already poisoning the writer.

Common situations: Rare in practice because the tar is written to an in-memory buffer; most often indicates a preceding failure (e.g. metadata encoding problem) or resource exhaustion (OOM) during packaging of very large packages.

Related errors

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