What causes "block metadata is empty" in hyperledger/fabric?

Pull from a different, healthy orderer endpoint

block metadata is empty

Error message

block metadata is empty

What it means

Block Metadata (e.g. the last-config metadata) is required by the block puller; a block with empty metadata cannot be validated for purposes like locating the latest config block. extractBlockFromResponse rejects it.

Source

Thrown at orderer/common/cluster/deliver.go:468

	}
	return stream, nil
}

func extractBlockFromResponse(resp *orderer.DeliverResponse) (*common.Block, error) {
	switch t := resp.Type.(type) {
	case *orderer.DeliverResponse_Block:
		block := t.Block
		if block == nil {
			return nil, errors.New("block is nil")
		}
		if block.Data == nil {
			return nil, errors.New("block data is nil")
		}
		if block.Header == nil {
			return nil, errors.New("block header is nil")
		}
		if block.Metadata == nil || len(block.Metadata.Metadata) == 0 {
			return nil, errors.New("block metadata is empty")
		}
		return block, nil
	case *orderer.DeliverResponse_Status:
		if t.Status == common.Status_FORBIDDEN {
			return nil, ErrForbidden
		}
		if t.Status == common.Status_SERVICE_UNAVAILABLE {
			return nil, ErrServiceUnavailable
		}
		return nil, errors.Errorf("faulty node, received: %v", resp)
	default:
		return nil, errors.Errorf("response is of type %v, but expected a block", reflect.TypeOf(resp.Type))
	}
}

func (p *BlockPuller) seekLastEnvelope() (*common.Envelope, error) {
	return protoutil.CreateSignedEnvelopeWithTLSBinding(
		common.HeaderType_DELIVER_SEEK_INFO,

View on GitHub (pinned to 2736b63f8f)

Solutions

Pull from a different, healthy orderer endpoint
Verify the source node's ledger metadata integrity
Align fabric versions across cluster nodes

Defensive patterns

Strategy: validation

Validate before calling

if md := resp.GetBlock().GetMetadata(); md == nil || len(md.Metadata) == 0 {
    return fmt.Errorf("block metadata missing in response")
}

Type guard

func hasBlockMetadata(resp *orderer.DeliverResponse) bool {
    md := resp.GetBlock().GetMetadata()
    return md != nil && len(md.Metadata) > 0
}

Try / catch

block, err := extractBlockFromResponse(resp)
if err != nil {
    return fmt.Errorf("invalid block from %s: %w", endpoint, err)
}

Prevention

Check metadata (esp. last-config) when using blocks for config discovery
Re-pull from a healthy endpoint when metadata is empty
Verify ledger integrity on nodes serving metadata-empty blocks

When it happens

Trigger: extractBlockFromResponse received a DeliverResponse_Block where block.Metadata is nil or block.Metadata.Metadata has zero entries.

Common situations: Source orderer serving a truncated/older-format block; corrupted metadata in the source ledger; binary version skew affecting metadata fields.

Related errors

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