hyperledger/fabric · error

failed to unmarshal envelope from bytes

Error message

failed to unmarshal envelope from bytes

What it means

InitFromBuffer attempts to proto.Unmarshal the package bytes into a common.Envelope and fails if the bytes are not a valid protobuf envelope. The error deliberately discards the underlying parse error. It means the input is not the expected signed chaincode package format at all.

Solutions

1. Confirm the input is the output of `peer chaincode signpackage` (a signed CDS envelope), not a CDS .tar.gz
2. Check the file is non-empty and fully transferred (compare sizes/checksums)
3. Regenerate the signed package from the original CDS

Example fix

// before
buf, _ := ioutil.ReadFile("mycc.cds") // tar CDS package, not an envelope
ccpack.InitFromBuffer(buf)
// after
buf, _ := ioutil.ReadFile("mycc-signed.pack") // signed CDS envelope from signpackage
ccpack.InitFromBuffer(buf)

func validateEnvelopeBytes(buf []byte) error {
    if len(buf) == 0 { return errors.New("empty package buffer") }
    env := &common.Envelope{}
    if err := proto.Unmarshal(buf, env); err != nil {
        return fmt.Errorf("not a valid signed CDS envelope: %w", err)
    }
    if env.Payload == nil { return errors.New("envelope has no payload") }
    return nil
}

func isEnvelope(buf []byte) bool {
    env := &common.Envelope{}
    return len(buf) > 0 && proto.Unmarshal(buf, env) == nil && env.Payload != nil
}

cd, err := GetCCPackage(buf, idFunc)
if err != nil {
    if strings.Contains(err.Error(), "failed to unmarshal envelope") {
        return fmt.Errorf("%s is not a signed chaincode package (did you pass a .cds tar?)", path)
    }
    return err
}

When it happens

Trigger: InitFromBuffer called (directly or via GetCCPackage / InitFromPath / processSignedCDS) with bytes that are not a valid common.Envelope: empty file, plain CDS bytes, tar package file, or random data.

Common situations: Pointing the installer at a .tar.gz CDS package instead of a signed CDS envelope; empty or truncated file; passing raw ChaincodeDeploymentSpec bytes.

Related errors

• error getting deployment spec
• error unmarshalling ChaicnodeEvent
• error unmarshalling ChaincodeAction
• error unmarshalling ChaincodeHeaderExtension
• error unmarshalling Response

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

Appendix: source

Thrown at core/common/ccprovider/sigcdspackage.go:227

	otherdata := &SignedCDSData{}
	err := proto.Unmarshal(ccdata.Data, otherdata)
	if err != nil {
		return err
	}

	if !proto.Equal(ccpack.data, otherdata) {
		return errors.New("data mismatch")
	}

	return nil
}

// InitFromBuffer sets the buffer if valid and returns ChaincodeData
func (ccpack *SignedCDSPackage) InitFromBuffer(buf []byte) (*ChaincodeData, error) {
	env := &common.Envelope{}
	err := proto.Unmarshal(buf, env)
	if err != nil {
		return nil, errors.New("failed to unmarshal envelope from bytes")
	}
	cHdr, sDepSpec, err := ccpackage.ExtractSignedCCDepSpec(env)
	if err != nil {
		return nil, err
	}

	if cHdr.Type != int32(common.HeaderType_CHAINCODE_PACKAGE) {
		return nil, errors.New("invalid type of envelope for chaincode package")
	}

	depSpec := &pb.ChaincodeDeploymentSpec{}
	err = proto.Unmarshal(sDepSpec.ChaincodeDeploymentSpec, depSpec)
	if err != nil {
		return nil, errors.New("error getting deployment spec")
	}

	databytes, id, data, err := ccpack.getCDSData(sDepSpec)
	if err != nil {

View on GitHub (pinned to 2736b63f8f)