hyperledger/fabric · error

header not set

Error message

header not set

What it means

ChannelHeader() extracts the common.ChannelHeader from an envelope. This error is thrown when the envelope's payload was successfully unmarshaled but its Header field is nil, meaning the envelope carries no header at all. The library refuses to proceed because every envelope in Fabric must carry a header identifying channel, type, and creator.

Source

Thrown at protoutil/commonutils.go:246

		return false
	}

	return cb.HeaderType(hdr.Type) == cb.HeaderType_CONFIG
}

// ChannelHeader returns the *cb.ChannelHeader for a given *cb.Envelope.
func ChannelHeader(env *cb.Envelope) (*cb.ChannelHeader, error) {
	if env == nil {
		return nil, errors.New("Invalid envelope payload. can't be nil")
	}

	envPayload, err := UnmarshalPayload(env.Payload)
	if err != nil {
		return nil, err
	}

	if envPayload.Header == nil {
		return nil, errors.New("header not set")
	}

	if envPayload.Header.ChannelHeader == nil {
		return nil, errors.New("channel header not set")
	}

	chdr, err := UnmarshalChannelHeader(envPayload.Header.ChannelHeader)
	if err != nil {
		return nil, errors.WithMessage(err, "error unmarshalling channel header")
	}

	return chdr, nil
}

// ChannelID returns the Channel ID for a given *cb.Envelope.
func ChannelID(env *cb.Envelope) (string, error) {
	chdr, err := ChannelHeader(env)
	if err != nil {

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Construct envelopes with protoutil.CreateEnvelope(payload, signer) or via protoutil.CreateSignedEnvelope so the header is populated
2. Verify the envelope source: call UnmarshalPayload yourself and check Payload.Header != nil before calling ChannelHeader
3. Check ChannelHeader(payload.Header) exists on the payload actually sent; fix the producer of the envelope
4. If consuming blocks, confirm the block was produced by a compatible Fabric version

Example fix

// before
env := &common.Envelope{Payload: payloadBytes}
chdr, err := protoutil.ChannelHeader(env) // panics path: "header not set"
// after
payload := &common.Payload{Header: &common.Header{ChannelHeader: chdrBytes, SignatureHeader: sigHdrBytes}, Data: data}
env, err := protoutil.CreateEnvelope(payload, signer)
chdr, err := protoutil.ChannelHeader(env)

payload, err := protoutil.UnmarshalPayload(env.Payload)
if err != nil { return err }
if payload == nil || payload.Header == nil { return errors.New("envelope payload has no header") }
chdr, err := protoutil.ChannelHeader(env)

func hasHeader(env *common.Envelope) bool {
	p, err := protoutil.UnmarshalPayload(env.GetPayload())
	return err == nil && p != nil && p.Header != nil
}

chdr, err := protoutil.ChannelHeader(env)
if err != nil {
	if err.Error() == "header not set" || err.Error() == "channel header not set" {
		return fmt.Errorf("malformed envelope from producer %s: %w", peerID, err)
	}
	return err
}

When it happens

Trigger: Calling protoutil.ChannelID, protoutil.BroadcastChannelSupport, protoutil.ConfigChannelHeader, protoutil.ConfigEnvelopeFromBlock, or protoutil.ChannelHeader with an *cb.Envelope whose payload deserializes to a *cb.Payload with Header == nil (e.g. an envelope built manually with only Payload set, or a payload that is not a TxPayload/ConfigPayload shape).

Common situations: Hand-crafting envelopes in tests or CLI tools without calling protoutil.CreateEnvelope; receiving malformed envelopes over the network from a misbehaving client; blocks/data produced by an older or incompatible Fabric version; passing a non-payload (e.g. marshaled different message) as env.Payload so Header is absent.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• bad header
• channel header not set
• error unmarshalling
• error encoding output
• error unmarshalling original config

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