What causes "block numbers not maintained in index" in hyperledger/fabric?

Include blkstorage.IndexableAttrBlockNum in the index attrs config

block numbers not maintained in index

Error message

block numbers not maintained in index

What it means

Duplicate slot for the family of 'block numbers not maintained in index': raised by blockIndex.getBlockLocByBlockNum when IndexableAttrBlockNum is absent from the index configuration. The operation is unsupported for this store's index settings.

Solutions

Include blkstorage.IndexableAttrBlockNum in the index attrs config
Restore default (full) indexing configuration
Recreate/rebuild index DB after config change

Example fix

// before
attrs: []blkstorage.IndexableAttr{blkstorage.IndexableAttrBlockHash}
// after
attrs: []blkstorage.IndexableAttr{blkstorage.IndexableAttrBlockHash, blkstorage.IndexableAttrBlockNum}

Defensive patterns

Strategy: validation

Validate before calling

func ensureBlockNumIndexed(cfg *blkstorage.IndexConfig) error {
    for _, a := range cfg.Attrs {
        if a == blkstorage.IndexableAttrBlockNum { return nil }
    }
    return errors.New("blockNum indexing disabled: by-number lookups unavailable")
}

Type guard

func blockNumIndexed(attrs []blkstorage.IndexableAttr) bool {
    for _, a := range attrs { if a == blkstorage.IndexableAttrBlockNum { return true } }
    return false
}

Try / catch

blk, err := store.RetrieveBlockByNumber(n)
if err != nil {
    if strings.Contains(err.Error(), "not maintained in index") {
        return iterateToBlock(n) // fallback: sequential iterator
    }
    return err
}

Prevention

Keep default full indexing config unless storage constraints are critical
Document which index attributes a deployment uses and guard by-number APIs on it
Recreate the index DB after changing indexAttrs

When it happens

Trigger: Any by-block-number retrieval (GetBlockByNumber/GetBlockHeaderByNumber), index range deletion, or syncIndex on a store configured without blockNum indexing.

Common situations: Custom minimal indexAttrs configs, mis-copied core.yaml, or programmatic blkstorage.Open with a restricted IndexConfig.

Related errors

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

Appendix: source

Thrown at common/ledger/blkstorage/blockindex.go:174

		return nil, errors.New("block hashes not maintained in index")
	}
	b, err := index.db.Get(constructBlockHashKey(blockHash))
	if err != nil {
		return nil, err
	}
	if b == nil {
		return nil, errors.Errorf("no such block hash [%x] in index", blockHash)
	}
	blkLoc := &fileLocPointer{}
	if err := blkLoc.unmarshal(b); err != nil {
		return nil, err
	}
	return blkLoc, nil
}

func (index *blockIndex) getBlockLocByBlockNum(blockNum uint64) (*fileLocPointer, error) {
	if !index.isAttributeIndexed(IndexableAttrBlockNum) {
		return nil, errors.New("block numbers not maintained in index")
	}
	b, err := index.db.Get(constructBlockNumKey(blockNum))
	if err != nil {
		return nil, err
	}
	if b == nil {
		return nil, errors.Errorf("no such block number [%d] in index", blockNum)
	}
	blkLoc := &fileLocPointer{}
	if err := blkLoc.unmarshal(b); err != nil {
		return nil, err
	}
	return blkLoc, nil
}

func (index *blockIndex) getTxLoc(txID string) (*fileLocPointer, error) {
	v, _, err := index.getTxIDVal(txID)
	if err != nil {

View on GitHub (pinned to 2736b63f8f)