{"record":{"id":"0d8faa1150d836f0","repo":"hyperledger/fabric","slug":"failed-unmarshalling-payload","errorCode":null,"errorMessage":"failed unmarshalling payload","messagePattern":"failed unmarshalling payload","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"orderer/consensus/smartbft/util.go","lineNumber":253,"sourceCode":"\t\treturn true\n\t}\n\n\treturn false\n}\n\nfunc (ri *RequestInspector) unwrapReq(req []byte) (*request, error) {\n\tenvelope, err := protoutil.UnmarshalEnvelope(req)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn ri.unwrapReqFromEnvelop(envelope)\n}\n\nfunc (ri *RequestInspector) unwrapReqFromEnvelop(envelope *cb.Envelope) (*request, error) {\n\tpayload := &cb.Payload{}\n\tif err := proto.Unmarshal(envelope.Payload, payload); err != nil {\n\t\treturn nil, errors.Wrap(err, \"failed unmarshalling payload\")\n\t}\n\n\tif payload.Header == nil {\n\t\treturn nil, errors.Errorf(\"no header in payload\")\n\t}\n\n\tsigHdr := &cb.SignatureHeader{}\n\tif err := proto.Unmarshal(payload.Header.SignatureHeader, sigHdr); err != nil {\n\t\treturn nil, err\n\t}\n\n\tif len(payload.Header.ChannelHeader) == 0 {\n\t\treturn nil, errors.New(\"no channel header in payload\")\n\t}\n\n\tchdr, err := protoutil.UnmarshalChannelHeader(payload.Header.ChannelHeader)\n\tif err != nil {\n\t\treturn nil, errors.WithMessage(err, \"error unmarshalling channel header\")","sourceCodeStart":235,"sourceCodeEnd":271,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/orderer/consensus/smartbft/util.go#L235-L271","documentation":"unwrapReqFromEnvelop wraps any proto.Unmarshal failure when deserializing the envelope's Payload bytes into cb.Payload, with the message 'failed unmarshalling payload'. It means the envelope.Payload byte slice is not a valid protobuf-encoded Payload — corrupt, truncated, empty-with-junk, or produced by an incompatible serialization. The wrapped underlying error names the specific protobuf decode failure.","triggerScenarios":"RequestID or requestIDFromEnvelope is given an envelope whose Payload bytes were corrupted in transit, truncated by storage, encrypted, or not a Payload protobuf at all.","commonSituations":"Manual crafting of envelopes with wrong payload bytes; corrupted ledger snapshots or file-backed message stores; forwarding raw bytes between incompatible Fabric versions; tests feeding arbitrary bytes as requests.","solutions":["Regenerate/re-submit the transaction with a correctly built payload (protoutil.MarshalOrPanic on a cb.Payload with proper ChannelHeader/SignatureHeader)","Verify the raw bytes decode: protoutil.UnmarshalPayload or configtxlator decode to identify the corruption point","Check for byte corruption in transport/storage (checksums, gossip compression, snapshot integrity)","Confirm sender and receiver run compatible Fabric/proto versions"],"exampleFix":"// before: raw/garbage payload\nenv := &cb.Envelope{Payload: someArbitraryBytes}\n// after\npayload, _ := protoutil.Marshal(&cb.Payload{Header: hdr, Data: data})\nenv := &cb.Envelope{Payload: payload}","handlingStrategy":"try-catch","validationCode":"func payloadDecodable(env *cb.Envelope) bool {\n    p := &cb.Payload{}\n    return env != nil && proto.Unmarshal(env.Payload, p) == nil && p.Header != nil\n}","typeGuard":null,"tryCatchPattern":"info, err := inspectPayload(raw) // wrapper around unwrapReqFromEnvelop\nif err != nil {\n    if strings.Contains(err.Error(), \"failed unmarshalling payload\") {\n        logger.Warnf(\"dropping malformed request: %v\", err)\n        return ErrMalformedRequest\n    }\n    return err\n}","preventionTips":["Only submit envelopes built by protoutil helpers, never hand-assembled protobuf bytes","Checksum raw requests in transit/storage to detect corruption","Keep Fabric versions aligned across orderers and clients"],"tags":["hyperledger-fabric","smartbft","protobuf","unmarshal","corrupt-payload"],"backgroundTag":"protobuf-unmarshal-failed","analyzedSha":"2736b63f8fd5932511d56fe68b7039d15977f7f6","analyzedAt":"2026-09-04T08:52:36.465Z","contentChangedAt":"2026-09-04T08:52:36.465Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}