hyperledger/fabric · error · ErrLedgerMgmtNotInitialized

ledger mgmt should be initialized before using

Error message

ledger mgmt should be initialized before using

What it means

ErrLedgerMgmtNotInitialized is a sentinel error returned by LedgerMgr methods when ledger management is used before Initialize/NewLedgerMgr has set up the package-level ledger manager. The ledger subsystem requires provider initialization (kvledger.NewProvider) before any Open/Create/Close operations can work.

Source

Thrown at core/ledger/ledgermgmt/ledger_mgmt.go:32

	"github.com/hyperledger/fabric-lib-go/common/flogging"
	"github.com/hyperledger/fabric-lib-go/common/metrics"
	"github.com/hyperledger/fabric-protos-go-apiv2/common"
	pb "github.com/hyperledger/fabric-protos-go-apiv2/peer"
	"github.com/hyperledger/fabric/core/common/ccprovider"
	"github.com/hyperledger/fabric/core/ledger"
	"github.com/hyperledger/fabric/core/ledger/cceventmgmt"
	"github.com/hyperledger/fabric/core/ledger/kvledger"
	"github.com/hyperledger/fabric/internal/fileutil"
	"github.com/pkg/errors"
)

var logger = flogging.MustGetLogger("ledgermgmt")

// ErrLedgerAlreadyOpened is thrown by a CreateLedger call if a ledger with the given id is already opened
var ErrLedgerAlreadyOpened = errors.New("ledger already opened")

// ErrLedgerMgmtNotInitialized is thrown when ledger mgmt is used before initializing this
var ErrLedgerMgmtNotInitialized = errors.New("ledger mgmt should be initialized before using")

// LedgerMgr manages ledgers for all channels
type LedgerMgr struct {
	creationLock         sync.Mutex
	joinBySnapshotStatus *pb.JoinBySnapshotStatus

	lock           sync.Mutex
	openedLedgers  map[string]ledger.PeerLedger
	ledgerProvider ledger.PeerLedgerProvider

	ebMetadataProvider MetadataProvider
}

type MetadataProvider interface {
	PackageMetadata(ccid string) ([]byte, error)
}

// Initializer encapsulates all the external dependencies for the ledger module

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Call ledgermgmt.Initialize(initializer) (or construct via NewLedgerMgr per the newer API) before any ledger operation, typically once at peer startup.
2. Check initialization order in your bootstrap code so no goroutine touches the ledger manager before initialization completes.
3. In tests, replicate the standard setup (constructLedgerMgrWithTestDefaults / TestLedgerMgmt pattern) before exercising ledger APIs.

Example fix

// before
lgr, err := ledgermgmt.OpenLedger(chanID) // panics/ErrLedgerMgmtNotInitialized

// after
ledgermgmt.Initialize(initializer) // must run first
lgr, err := ledgermgmt.OpenLedger(chanID)

// ensure ledgermgmt is initialized before any ledger call
if ledgerMgr == nil || !ledgerMgmtInitialized.Load() {
    return fmt.Errorf("ledger mgmt not initialized; call Initialize/NewLedgerMgr first")
}

func IsLedgerMgmtNotInitialized(err error) bool {
    return errors.Is(err, ledgermgmt.ErrLedgerMgmtNotInitialized)
}

lgr, err := ledgermgmt.OpenLedger(chanID)
if err != nil {
    if errors.Is(err, ledgermgmt.ErrLedgerMgmtNotInitialized) {
        return fmt.Errorf("bootstrap bug: ledger mgmt used before initialization: %w", err)
    }
    return err
}

When it happens

Trigger: Calling ledgermgmt functions such as OpenLedger, CreateLedger, CloseLedger, or GetLedgerIDs before ledgermgmt.Initialize(...) (or NewLedgerMgr + initialization) has run; unit tests or embedded usage that skip peer bootstrap; calling after initialization failed and left ledgerMgr nil.

Common situations: Embedding Fabric ledger code in a custom application without running the normal peer bootstrap; writing tests that call OpenLedger without a TestLedgerMgmt-style setup; ordering bugs where a component accesses ledgers before the node finishes initialization.

Related errors

• ledger already opened
• Value of File: was nil
• id cannot be nil if buf is not nil
• depspec cannot be nil if buf is not nil
• nil data bytes

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