hyperledger/fabric · error

Invalid envelope payload. can't be nil

Error message

Invalid envelope payload. can't be nil

What it means

ChannelHeader(env) extracts the *cb.ChannelHeader for an envelope by first unmarshaling its payload. If the *cb.Envelope argument itself is nil, the function returns 'Invalid envelope payload. can't be nil' rather than dereferencing it. It is the entry-level nil guard of a chain that can also fail later with 'header not set' or 'channel header not set'.

Source

Thrown at protoutil/commonutils.go:237

		return false
	}

	if payload.Header == nil {
		return false
	}

	hdr, err := UnmarshalChannelHeader(payload.Header.ChannelHeader)
	if err != nil {
		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")

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Check env != nil before calling ChannelHeader or its wrappers (ChannelID, isConfig, etc.).
2. Fix the upstream producer of the nil envelope — usually a failed ExtractEnvelope/GetEnvelopeFromBlock whose error was ignored.
3. When iterating block data, skip or log entries that fail to decode instead of passing nil onward.
4. Wrap the call in error handling so 'Invalid envelope payload' distinguishes nil envelopes from real unmarshal failures in logs.

Example fix

// before
chdr, err := protoutil.ChannelHeader(env) // env may be nil
// after
if env == nil {
    return errors.New("skipping block entry: no envelope")
}
chdr, err := protoutil.ChannelHeader(env)

func channelHeaderSafe(env *cb.Envelope) (*cb.ChannelHeader, error) {
    if env == nil {
        return nil, errors.New("nil envelope")
    }
    return protoutil.ChannelHeader(env)
}

func isEnvelope(e *cb.Envelope) bool {
    return e != nil && len(e.Payload) > 0
}

chdr, err := protoutil.ChannelHeader(env)
if err != nil {
    switch {
    case err.Error() == "Invalid envelope payload. can't be nil":
        return errors.New("caller passed nil envelope")
    case err.Error() == "header not set", err.Error() == "channel header not set":
        return fmt.Errorf("envelope missing header fields: %w", err)
    }
    return err
}

When it happens

Trigger: Passing a nil *cb.Envelope to ChannelHeader, ChannelID, isConfig, ConfigChannelHeader, or ConfigEnvelopeFromBlock — e.g. an extraction step returned nil and was propagated unchecked, or a loop over empty block data.

Common situations: Processing blocks whose envelope extraction failed upstream (nil envelope error swallowed); map lookups or slices yielding nil envelopes; tooling iterating blocks from a partially-written ledger where an envelope slot is nil.

Related errors

• no config found in envelope
• block must be different from nil, channel=%s
• channel header not found in the envelope
• Invalid signed proposal during check policy on channel [%s]
• proto: Marshal called with nil

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