hyperledger/fabric · error

failed to unmarshal channel header

Error message

failed to unmarshal channel header

What it means

Returned by NewBundleFromEnvelope when protoutil.UnmarshalChannelHeader fails to decode the payload's channel header bytes. The envelope had a header, but the channel header field is not valid protobuf, so the channel identity of the config cannot be established.

Source

Thrown at common/channelconfig/bundle.go:186

// information from a full configtx
func NewBundleFromEnvelope(env *cb.Envelope, bccsp bccsp.BCCSP) (*Bundle, error) {
	payload, err := protoutil.UnmarshalPayload(env.Payload)
	if err != nil {
		return nil, errors.Wrap(err, "failed to unmarshal payload from envelope")
	}

	configEnvelope, err := configtx.UnmarshalConfigEnvelope(payload.Data)
	if err != nil {
		return nil, errors.Wrap(err, "failed to unmarshal config envelope from payload")
	}

	if payload.Header == nil {
		return nil, errors.Errorf("envelope header cannot be nil")
	}

	chdr, err := protoutil.UnmarshalChannelHeader(payload.Header.ChannelHeader)
	if err != nil {
		return nil, errors.Wrap(err, "failed to unmarshal channel header")
	}

	return NewBundle(chdr.ChannelId, configEnvelope.Config, bccsp)
}

// NewBundle creates a new immutable bundle of configuration
func NewBundle(channelID string, config *cb.Config, bccsp bccsp.BCCSP) (*Bundle, error) {
	if err := preValidate(config); err != nil {
		return nil, err
	}

	channelConfig, err := NewChannelConfig(config.ChannelGroup, bccsp)
	if err != nil {
		return nil, errors.Wrap(err, "initializing channelconfig failed")
	}

	policyProviderMap := make(map[int32]policies.Provider)
	for pType := range cb.Policy_PolicyType_name {

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Inspect the wrapped decode error for details
2. Use a well-formed config envelope from a real Fabric block

When it happens

Trigger: Thrown at common/channelconfig/bundle.go:186 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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