hyperledger/fabric · error

could not unmarshall channel header

Error message

could not unmarshall channel header

What it means

ValidateUpdateConfigEnvelope guard: protoutil.UnmarshalChannelHeader failed on payload.Header.ChannelHeader, meaning the channel header bytes are not a valid protobuf ChannelHeader message. The update-config envelope is structurally malformed.

Source

Thrown at orderer/common/channelparticipation/validator.go:85

// ValidateUpdateConfigEnvelope checks whether this envelope can be used as an update config for the channel participation API.
// It returns the channel ID.
// It verifies that it is not a system channel by checking that consortiums config does not exist.
// It verifies it is an application channel by checking that the application group exists.
// It returns an error when it cannot be used as a update config envelope.
func ValidateUpdateConfigEnvelope(env *cb.Envelope) (channelID string, err error) {
	payload, err := protoutil.UnmarshalPayload(env.Payload)
	if err != nil {
		return "", errors.New("bad payload")
	}

	if payload.Header == nil || payload.Header.ChannelHeader == nil {
		return "", errors.New("bad header")
	}

	ch, err := protoutil.UnmarshalChannelHeader(payload.Header.ChannelHeader)
	if err != nil {
		return "", errors.New("could not unmarshall channel header")
	}

	if ch.Type != int32(cb.HeaderType_CONFIG_UPDATE) {
		return "", errors.New("bad type")
	}

	if ch.ChannelId == "" {
		return "", errors.New("empty channel id")
	}

	configUpdateEnv, err := protoutil.EnvelopeToConfigUpdate(env)
	if err != nil {
		return "", err
	}

	configUpdate, err := configtx.UnmarshalConfigUpdate(configUpdateEnv.ConfigUpdate)
	if err != nil {
		return "", err

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Re-marshal the ChannelHeader from a typed struct (cb.ChannelHeader) instead of passing arbitrary bytes.
2. Compare the bytes against a known-good envelope generated by configtxlator or the fabric CLI.
3. Align client and orderer Fabric versions so the common.ChannelHeader protobuf definition matches.
4. Log/decode the header locally with protoutil.UnmarshalChannelHeader to reproduce the parse failure before submitting.

Example fix

// before
hdrBytes := customSerialize(header) // not valid protobuf
// after
ch := &cb.ChannelHeader{Type: int32(cb.HeaderType_CONFIG_UPDATE), ChannelId: "mychannel"}
hdrBytes, _ := protoutil.Marshal(ch)

hdr, err := protoutil.UnmarshalChannelHeader(payload.Header.ChannelHeader)
if err != nil { return fmt.Errorf("channel header not decodable: %w", err) }

func isDecodableChannelHeader(b []byte) bool {
    _, err := protoutil.UnmarshalChannelHeader(b)
    return err == nil
}

_, err := ValidateUpdateConfigEnvelope(env)
if err != nil && strings.Contains(err.Error(), "could not unmarshall channel header") {
    // re-marshal header from a typed cb.ChannelHeader and resubmit
}

When it happens

Trigger: Sending an envelope whose ChannelHeader bytes are corrupted, mis-marshaled, or belong to a different protobuf type to the channel participation update endpoint.

Common situations: Mismatches between client and server protobuf definitions after a Fabric upgrade; raw byte injection from custom tooling; corrupted output of a serialization step in an intermediate proxy that rewrites envelopes.

Related errors

• bad payload
• bad header
• failed extracting envelope from block
• error unmarshalling
• error encoding output

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