hyperledger/fabric · error

failed extracting envelope from block

Error message

failed extracting envelope from block

What it means

After confirming the block has data, validateBootstrapBlock unmarshals the first envelope from block.Data.Data[0] as a common.Envelope. If protobuf unmarshaling fails, the block bytes are not a valid Fabric envelope and the error is wrapped as 'failed extracting envelope from block'.

Solutions

1. Regenerate the block with the same Fabric version's configtxgen and retry the join
2. Validate the block with 'configtxgen -inspectBlock' or 'configtxlator decode' to confirm it parses
3. Re-transfer the block file and compare checksums to rule out corruption
4. Ensure osnadmin and orderer binaries come from the same Fabric release

Example fix

// before
osnadmin channel join --channelID mychannel --config-block channel.json
// after
configtxgen -profile TwoOrgsChannel -outputBlock /tmp/genesis.block -channelID mychannel
osnadmin channel join --channelID mychannel --config-block /tmp/genesis.block

env := &common.Envelope{}
if err := proto.Unmarshal(block.Data.Data[0], env); err != nil {
    return fmt.Errorf("config block is not a valid Fabric envelope: %w", err)
}

func isParseableEnvelope(b *common.Block) error {
    if b == nil || b.Data == nil || len(b.Data.Data) == 0 {
        return errors.New("no block data")
    }
    e := &common.Envelope{}
    return proto.Unmarshal(b.Data.Data[0], e)
}

When it happens

Trigger: 'osnadmin channel join' (or verifyNoSystemChannel paths) given a config block whose first payload cannot be proto-unmarshaled into common.Envelope — corrupted bytes, wrong file format, or a block from an incompatible version.

Common situations: Using a block file produced by a different tool/format, copying a block over the network with corruption, accidentally passing a PEM cert, tarball, or JSON config as the --config-block.

Related errors

• empty block data
• bad header
• bad payload
• could not convert message to signedData
• could not unmarshall channel header

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

Appendix: source

Thrown at orderer/common/server/util.go:54

		return nil, errors.WithMessage(err, "Error in opening ledger factory")
	}
	return lf, nil
}

// validateBootstrapBlock returns whether this block can be used as a bootstrap block.
// A bootstrap block is a block of a system channel, and needs to have a ConsortiumsConfig.
func validateBootstrapBlock(block *common.Block, bccsp bccsp.BCCSP) error {
	if block == nil {
		return errors.New("nil block")
	}

	if block.Data == nil || len(block.Data.Data) == 0 {
		return errors.New("empty block data")
	}

	firstTransaction := &common.Envelope{}
	if err := proto.Unmarshal(block.Data.Data[0], firstTransaction); err != nil {
		return errors.Wrap(err, "failed extracting envelope from block")
	}

	bundle, err := channelconfig.NewBundleFromEnvelope(firstTransaction, bccsp)
	if err != nil {
		return err
	}

	_, exists := bundle.ConsortiumsConfig()
	if !exists {
		return errors.New("the block isn't a system channel block because it lacks ConsortiumsConfig")
	}
	return nil
}

type clock struct{}

func (c *clock) Now() time.Time {
	return time.Now()

View on GitHub (pinned to 2736b63f8f)