hyperledger/fabric · error

error unmarshalling message for type %s

Error message

error unmarshalling message for type %s

What it means

After confirming the header type, UnmarshalEnvelopeOfType unmarshals payload.Data into the caller-supplied proto message; on failure it wraps the underlying proto error with 'error unmarshalling message for type %s'. This means the bytes in the payload do not decode as the expected protobuf message type for that header type.

Source

Thrown at protoutil/commonutils.go:79

	if err != nil {
		return nil, err
	}

	if payload.Header == nil {
		return nil, errors.New("envelope must have a Header")
	}

	chdr, err := UnmarshalChannelHeader(payload.Header.ChannelHeader)
	if err != nil {
		return nil, err
	}

	if chdr.Type != int32(headerType) {
		return nil, errors.Errorf("invalid type %s, expected %s", cb.HeaderType(chdr.Type), headerType)
	}

	err = proto.Unmarshal(payload.Data, message)
	err = errors.Wrapf(err, "error unmarshalling message for type %s", headerType)
	return chdr, err
}

// ExtractEnvelopeOrPanic retrieves the requested envelope from a given block
// and unmarshals it -- it panics if either of these operations fail
func ExtractEnvelopeOrPanic(block *cb.Block, index int) *cb.Envelope {
	envelope, err := ExtractEnvelope(block, index)
	if err != nil {
		panic(err)
	}
	return envelope
}

// ExtractEnvelope retrieves the requested envelope from a given block and
// unmarshals it
func ExtractEnvelope(block *cb.Block, index int) (*cb.Envelope, error) {
	if block.Data == nil {
		return nil, errors.New("block data is nil")

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Inspect the wrapped inner error (errors.Wrapf preserves it) to identify whether it is truncated data or a wire-type mismatch.
2. Re-check what component produced the envelope: re-marshal the message with the matching proto type before placing it in payload.Data.
3. If data came from a block store or snapshot, verify storage integrity / re-fetch the block from the ordering service.
4. Ensure the peer/orderer/SDK versions agree on the protobuf definitions (fabric-protos) — version skew changes message shapes.

// sanity-check the payload bytes are non-empty before unmarshaling
if env == nil || len(env.Payload) == 0 {
    return errors.New("envelope has no payload bytes")
}
payload, err := protoutil.UnmarshalPayload(env.Payload)
if err != nil || len(payload.Data) == 0 {
    return fmt.Errorf("payload missing or empty Data: %w", err)
}

func hasNonEmptyPayloadData(env *cb.Envelope) bool {
    p, err := protoutil.UnmarshalPayload(env.Payload)
    return err == nil && p != nil && len(p.Data) > 0
}

if err := protoutil.UnmarshalEnvelopeOfType(env, cb.HeaderType_CONFIG, &configEnv); err != nil {
    logger.Errorf("unmarshal failed for %s: %+v", cb.HeaderType_CONFIG, err) // errors.Wrapf keeps the cause
    // fall back to re-fetching the block from the ordering service
    return retryFetch(blockNum)
}

When it happens

Trigger: proto.Unmarshal(payload.Data, message) returns an error — payload.Data holds bytes of a different message type than the header claims, truncated/corrupted data, or the envelope was constructed by hand with wrong Data bytes.

Common situations: Corrupted blocks read from file storage (peer's block store), payloads generated by an incompatible Fabric version or an external tool writing malformed protobuf, custom chaincode manually assembling envelopes with incorrectly marshaled Data.

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 Envelope
• 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/1323f35a32a441ca. Report an issue: GitHub.