hyperledger/fabric · error

unmarshalling envelope: %s

Error message

unmarshalling envelope: %s

What it means

validateEnvelopeChannelID unmarshals the --configUpdateEnvelope bytes into common.Envelope; a proto.Unmarshal failure is wrapped as this error. It indicates the file is not a valid protobuf-encoded fabric envelope.

Source

Thrown at cmd/osnadmin/main.go:235

	blockChannelID, err := protoutil.GetChannelIDFromBlock(block)
	if err != nil {
		return err
	}

	// quick sanity check that the orderer admin is joining
	// the channel they think they're joining.
	if channelID != blockChannelID {
		return fmt.Errorf("specified --channelID %s does not match channel ID %s in config block", channelID, blockChannelID)
	}

	return nil
}

func validateEnvelopeChannelID(envelopeBytes []byte, channelID string) error {
	envelope := &common.Envelope{}
	err := proto.Unmarshal(envelopeBytes, envelope)
	if err != nil {
		return fmt.Errorf("unmarshalling envelope: %s", err)
	}

	envelopeChannelID, err := protoutil.GetChannelIDFromEnvelope(envelope)
	if err != nil {
		return err
	}

	// quick sanity check that the orderer admin is joining
	// the channel they think they're joining.
	if channelID != envelopeChannelID {
		return fmt.Errorf("specified --channelID %s does not match channel ID %s in config update envelope", channelID, envelopeChannelID)
	}

	return nil
}

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Regenerate the envelope with configtxgen (e.g. -outputUpdateChannelUpdate or -outputAnchorPeersUpdate).
2. Confirm the file is the envelope, not the block or other artifact.
3. Re-transfer the file to rule out corruption.
4. Verify fabric binary versions match between artifact generation and use.

Example fix

// before
osnadmin channel update --configUpdateEnvelope mychannel.block
// after
osnadmin channel update --configUpdateEnvelope config_update_envelope.pb

func looksLikeEnvelope(b []byte) bool {
    env := &common.Envelope{}
    return proto.Unmarshal(b, env) == nil && env.Payload != nil
}
// run before invoking osnadmin update

func isProtoEnvelope(b []byte) bool {
    env := &common.Envelope{}
    if proto.Unmarshal(b, env) != nil { return false }
    return env.Payload != nil && env.Signature != nil
}

if err := runOsnadmin(); err != nil {
    if strings.Contains(err.Error(), "unmarshalling envelope:") {
        log.Fatalf("--configUpdateEnvelope is not a valid protobuf envelope: %v", err)
    }
}

When it happens

Trigger: Providing a block instead of an envelope, a JSON/YAML configtx artifact, a corrupted or empty file, or a gzipped envelope.

Common situations: Mixing up configtxgen outputs (block vs envelope), corruption during container copy, or using an envelope from a different fabric major version.

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

• unmarshalling block: %s
• invalid chaincode event
• nil SignatureHeader provided
• nil ChannelHeader provided
• envelope must have a Header

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