hyperledger/fabric · error

error unmarshalling ChaincodeHeaderExtension

Error message

error unmarshalling ChaincodeHeaderExtension

What it means

Returned by protoutil.UnmarshalChaincodeHeaderExtension when proto.Unmarshal fails to decode the header extension bytes into a peer.ChaincodeHeaderExtension. The wrap adds the failing message type to the protobuf error. It means the hdrExtension bytes are not a validly encoded ChaincodeHeaderExtension.

Source

Thrown at protoutil/unmarshalers.go:109

// UnmarshalHeader unmarshals bytes to a Header
func UnmarshalHeader(bytes []byte) (*common.Header, error) {
	hdr := &common.Header{}
	err := proto.Unmarshal(bytes, hdr)
	return hdr, errors.Wrap(err, "error unmarshalling Header")
}

// UnmarshalConfigEnvelope unmarshals bytes to a ConfigEnvelope
func UnmarshalConfigEnvelope(bytes []byte) (*common.ConfigEnvelope, error) {
	cfg := &common.ConfigEnvelope{}
	err := proto.Unmarshal(bytes, cfg)
	return cfg, errors.Wrap(err, "error unmarshalling ConfigEnvelope")
}

// UnmarshalChaincodeHeaderExtension unmarshals bytes to a ChaincodeHeaderExtension
func UnmarshalChaincodeHeaderExtension(hdrExtension []byte) (*peer.ChaincodeHeaderExtension, error) {
	chaincodeHdrExt := &peer.ChaincodeHeaderExtension{}
	err := proto.Unmarshal(hdrExtension, chaincodeHdrExt)
	return chaincodeHdrExt, errors.Wrap(err, "error unmarshalling ChaincodeHeaderExtension")
}

// UnmarshalProposalResponse unmarshals bytes to a ProposalResponse
func UnmarshalProposalResponse(prBytes []byte) (*peer.ProposalResponse, error) {
	proposalResponse := &peer.ProposalResponse{}
	err := proto.Unmarshal(prBytes, proposalResponse)
	return proposalResponse, errors.Wrap(err, "error unmarshalling ProposalResponse")
}

// UnmarshalChaincodeAction unmarshals bytes to a ChaincodeAction
func UnmarshalChaincodeAction(caBytes []byte) (*peer.ChaincodeAction, error) {
	chaincodeAction := &peer.ChaincodeAction{}
	err := proto.Unmarshal(caBytes, chaincodeAction)
	return chaincodeAction, errors.Wrap(err, "error unmarshalling ChaincodeAction")
}

// UnmarshalResponse unmarshals bytes to a Response
func UnmarshalResponse(resBytes []byte) (*peer.Response, error) {

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Verify the proposal's ChannelHeader.Extension is set and marshaled as a ChaincodeHeaderExtension (chaincode_id field).
2. Check the channel header type is ENDORSER_TRANSACTION before unmarshaling the extension.
3. Confirm the SDK used to build the transaction matches the peer's Fabric version.
4. Guard against empty extension bytes and skip/return early when extension is absent.
5. Log the failing bytes (length + base64) to confirm the wrong message type isn't being passed.

Example fix

// before
ext, _ := protoutil.UnmarshalChaincodeHeaderExtension(chdr.Extension) // may be empty
// after
if len(chdr.Extension) == 0 {
    return nil, errors.New("missing chaincode header extension")
}
ext, err := protoutil.UnmarshalChaincodeHeaderExtension(chdr.Extension)
if err != nil {
    return nil, fmt.Errorf("bad header extension: %w", err)
}

func hasHeaderExtension(chdr *common.ChannelHeader) bool {
    return chdr.Type == int32(common.HeaderType_ENDORSER_TRANSACTION) && len(chdr.Extension) > 0
}

func isChaincodeHeaderExtension(v any) bool {
    ext, ok := v.(*peer.ChaincodeHeaderExtension)
    return ok && ext.ChaincodeId != nil
}

ext, err := protoutil.UnmarshalChaincodeHeaderExtension(chdr.Extension)
if err != nil {
    return nil, fmt.Errorf("missing/invalid header extension: %w", err)
}

When it happens

Trigger: Calling UnmarshalChaincodeHeaderExtension on channel header extensions that are empty, truncated, or belong to a different message type (e.g. config-style extension bytes); reached from getTxCCInstance, proposal validation, and TestProposal paths.

Common situations: Processing proposals whose ChannelHeader.Extension was not populated by the SDK; parsing blocks from a different Fabric version where extension semantics changed; hand-built proposals omitting the extension.

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

• error unmarshalling ChaincodeAction
• error unmarshalling Response
• error unmarshalling ChaicnodeEvent
• error unmarshalling Proposal
• error unmarshalling ChaincodeProposalPayload

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