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.

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)

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
• failed to deserialize values
• panic(err)
• Error unmarshalling to ImplicitMetaPolicy: %s
• unknown operation type

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