hyperledger/fabric · error

error decoding the block number

Error message

error decoding the block number

What it means

deserializeBlock/extractSerializedBlockInfo decode Fabric's flat serialized block format via a buffer. extractHeader first decodes the block number as a varint; if the buffer is exhausted or corrupted at that point, this wrapped error is returned. It indicates the serialized bytes are not a valid Fabric block.

Source

Thrown at common/ledger/blkstorage/block_serialization.go:119

	numItems := uint64(0)
	if blockMetadata != nil {
		numItems = uint64(len(blockMetadata.Metadata))
	}
	buf = protowire.AppendVarint(buf, numItems)
	if blockMetadata == nil {
		return buf
	}
	for _, b := range blockMetadata.Metadata {
		buf = protowire.AppendBytes(buf, b)
	}
	return buf
}

func extractHeader(buf *buffer) (*common.BlockHeader, error) {
	header := &common.BlockHeader{}
	var err error
	if header.Number, err = buf.DecodeVarint(); err != nil {
		return nil, errors.Wrap(err, "error decoding the block number")
	}
	if header.DataHash, err = buf.DecodeRawBytes(false); err != nil {
		return nil, errors.Wrap(err, "error decoding the data hash")
	}
	if header.PreviousHash, err = buf.DecodeRawBytes(false); err != nil {
		return nil, errors.Wrap(err, "error decoding the previous hash")
	}
	if len(header.PreviousHash) == 0 {
		header.PreviousHash = nil
	}
	return header, nil
}

func extractData(buf *buffer) (*common.BlockData, []*txindexInfo, error) {
	data := &common.BlockData{}
	var txOffsets []*txindexInfo
	var numItems uint64
	var err error

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Verify the block file integrity; restore the ledger block files from a known-good backup or re-fetch blocks from another peer/orderer.
2. Stop the node, remove the corrupted channel's ledger data, and re-join the channel to rebuild the ledger from genesis.
3. Check disk health and free space on the peer's ledger volume.
4. Confirm the code path passes serialized block bytes, not raw protobuf Block bytes, into the deserializer.

Example fix

null

if len(serializedBlockBytes) == 0 {
    return errors.New("refusing to deserialize empty block bytes")
}

func looksLikeSerializedBlock(b []byte) bool {
    return len(b) > 4 // varint number + hashes + framing must be present
}

block, err := deserializeBlock(buf)
if err != nil && strings.Contains(err.Error(), "error decoding the block number") {
    logger.Errorf("corrupt block at head of store: %v", err)
    // quarantine the file and resync from peers
}

When it happens

Trigger: Calling blkstorage deserialization (deserializeBlock, extractSerializedBlockInfo, e.g. via GetBlockByHash/GetBlockByNumber internals) on bytes that are empty, truncated, or not produced by serializeBlock.

Common situations: Corrupted ledger files on disk (disk full at write time, crash during commit); copying/moving ledger files between nodes without stopping; restoring block files from a partial backup; pointing blkstorage at a directory containing foreign data.

Related errors

• error decoding the data hash
• error decoding the previous hash
• error decoding the length of block data
• error decoding the transaction envelope
• error decoding the length of block metadata

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