hyperledger/fabric · error

failed unmarshalling payload

Error message

failed unmarshalling payload

What it means

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.

Source

Thrown at orderer/consensus/smartbft/util.go:253

		return true
	}

	return false
}

func (ri *RequestInspector) unwrapReq(req []byte) (*request, error) {
	envelope, err := protoutil.UnmarshalEnvelope(req)
	if err != nil {
		return nil, err
	}

	return ri.unwrapReqFromEnvelop(envelope)
}

func (ri *RequestInspector) unwrapReqFromEnvelop(envelope *cb.Envelope) (*request, error) {
	payload := &cb.Payload{}
	if err := proto.Unmarshal(envelope.Payload, payload); err != nil {
		return nil, errors.Wrap(err, "failed unmarshalling payload")
	}

	if payload.Header == nil {
		return nil, errors.Errorf("no header in payload")
	}

	sigHdr := &cb.SignatureHeader{}
	if err := proto.Unmarshal(payload.Header.SignatureHeader, sigHdr); err != nil {
		return nil, err
	}

	if len(payload.Header.ChannelHeader) == 0 {
		return nil, errors.New("no channel header in payload")
	}

	chdr, err := protoutil.UnmarshalChannelHeader(payload.Header.ChannelHeader)
	if err != nil {
		return nil, errors.WithMessage(err, "error unmarshalling channel header")

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Regenerate/re-submit the transaction with a correctly built payload (protoutil.MarshalOrPanic on a cb.Payload with proper ChannelHeader/SignatureHeader)
2. Verify the raw bytes decode: protoutil.UnmarshalPayload or configtxlator decode to identify the corruption point
3. Check for byte corruption in transport/storage (checksums, gossip compression, snapshot integrity)
4. Confirm sender and receiver run compatible Fabric/proto versions

Example fix

// before: raw/garbage payload
env := &cb.Envelope{Payload: someArbitraryBytes}
// after
payload, _ := protoutil.Marshal(&cb.Payload{Header: hdr, Data: data})
env := &cb.Envelope{Payload: payload}

func payloadDecodable(env *cb.Envelope) bool {
    p := &cb.Payload{}
    return env != nil && proto.Unmarshal(env.Payload, p) == nil && p.Header != nil
}

info, err := inspectPayload(raw) // wrapper around unwrapReqFromEnvelop
if err != nil {
    if strings.Contains(err.Error(), "failed unmarshalling payload") {
        logger.Warnf("dropping malformed request: %v", err)
        return ErrMalformedRequest
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "cannot parse invalid wire-format data", "cannot unmarshal", "failed unmarshalling": protobuf unmarshal errors explained — this error's family across 10 libraries.

Related errors

• failed unmarshalling envelope of config block
• failed to deserialize values
• error converting envelope to config update: %s
• failed to unmarshal response for transaction %s
• unmarshalling ChaincodeQueryResponse failed

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