hyperledger/fabric · error

error unmarshalling Header

Error message

error unmarshalling Header

What it means

Returned by protoutil.UnmarshalHeader when proto.Unmarshal cannot decode the bytes into a common.Header message. The library wraps the protobuf error so the failing message type is clear. It means the payload is not a validly encoded Header (wrong type, truncated, or corrupted).

Source

Thrown at protoutil/unmarshalers.go:95

// UnmarshalIdentifierHeader unmarshals bytes to an IdentifierHeader
func UnmarshalIdentifierHeader(bytes []byte) (*common.IdentifierHeader, error) {
	ih := &common.IdentifierHeader{}
	err := proto.Unmarshal(bytes, ih)
	return ih, errors.Wrap(err, "error unmarshalling IdentifierHeader")
}

func UnmarshalSerializedIdentity(bytes []byte) (*msp.SerializedIdentity, error) {
	sid := &msp.SerializedIdentity{}
	err := proto.Unmarshal(bytes, sid)
	return sid, errors.Wrap(err, "error unmarshalling SerializedIdentity")
}

// 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) {

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Confirm the bytes are exactly the Header portion (ChannelHeader+SignatureHeader) of the payload, not the whole payload or envelope.
2. Validate non-empty, non-truncated input before calling; log length and first bytes on failure.
3. Regenerate the proposal/transaction with a matching Fabric SDK/peer version.
4. Check that channel header and signature header byte slices were not concatenated or swapped.
5. Wrap the error with request context and reject the transaction/proposal cleanly.

Example fix

// before
hdr, _ := protoutil.UnmarshalHeader(payloadBytes) // wrong slice: whole payload
// after
hdr, err := protoutil.UnmarshalHeader(payload.Header)
if err != nil {
    return fmt.Errorf("invalid payload header: %w", err)
}

func validHeader(b []byte) bool {
    hdr := &common.Header{}
    return len(b) > 0 && proto.Unmarshal(b, hdr) == nil && hdr.ChannelHeader != nil
}

func isHeader(v any) bool {
    _, ok := v.(*common.Header)
    return ok
}

hdr, err := protoutil.UnmarshalHeader(b)
if err != nil {
    return nil, fmt.Errorf("malformed header (%d bytes): %w", len(b), err)
}

When it happens

Trigger: Calling UnmarshalHeader on signature/payload header bytes that are empty, truncated, belong to a different message type (e.g. a SerializedIdentity), or were produced with mismatched protobuf definitions; invoked from CheckACL, getSignedData, UnpackProposal, and proposal validation paths.

Common situations: Submitting hand-crafted proposals with malformed headers; ACL checks on corrupted transactions read from a block; channel header/signature header swapped; SDK/peer protobuf version drift.

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
• error unmarshalling original config
• error unmarshalling updated config
• failed to unmarshal ApplicationPolicy bytes
• could not unmarshal signature policy envelope

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