hyperledger/fabric · error

error unmarshalling ConfigEnvelope

Error message

error unmarshalling ConfigEnvelope

What it means

Returned by protoutil.UnmarshalConfigEnvelope when proto.Unmarshal fails to decode bytes into a common.ConfigEnvelope. The wrapper adds the message-type context to the raw protobuf error. It signals the configuration bytes are invalid, of the wrong type, or corrupted.

Source

Thrown at protoutil/unmarshalers.go:102

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

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Ensure you pass payload.Data of a CONFIG-type envelope, not an ENDORSER_TRANSACTION payload.
2. Verify the bytes were produced by marshaling a common.ConfigEnvelope (e.g. via configtxgen output), not raw JSON/YAML.
3. Check the block type in the channel header before attempting to unmarshal.
4. Align Fabric tooling (configtxgen, SDK) versions with the orderer.
5. Log length and hex prefix of failing bytes to detect truncation/corruption.

Example fix

// before
cfg, _ := protoutil.UnmarshalConfigEnvelope(block.Data)
// after
env, _ := protoutil.UnmarshalEnvelope(block.Data)
payload, _ := protoutil.UnmarshalPayload(env.Payload)
cfg, err := protoutil.UnmarshalConfigEnvelope(payload.Data)
if err != nil {
    return fmt.Errorf("not a config envelope: %w", err)
}

func isConfigBlock(chdr *common.ChannelHeader) bool {
    return chdr.Type == int32(common.HeaderType_CONFIG)
}

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

cfg, err := protoutil.UnmarshalConfigEnvelope(payload.Data)
if err != nil {
    return fmt.Errorf("payload is not a config envelope: %w", err)
}

When it happens

Trigger: Calling UnmarshalConfigEnvelope on block data/payload bytes that are not a ConfigEnvelope (e.g. an ordinary transaction payload), empty bytes, truncated config updates, or config generated by an incompatible Fabric version; used in addNodeToConfig/removeNodeFromConfig flows.

Common situations: Processing config blocks and extracting the envelope from the wrong payload field; passing config update JSON/YAML bytes instead of the marshaled protobuf; channel creation tooling version mismatch.

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/392e558313d147fe. Report an issue: GitHub.