{"record":{"id":"d226afe35c8fe7e2","repo":"hyperledger/fabric","slug":"ledger-mgmt-should-be-initialized-before-using","errorCode":null,"errorMessage":"ledger mgmt should be initialized before using","messagePattern":"ledger mgmt should be initialized before using","errorType":"exception","errorClass":"ErrLedgerMgmtNotInitialized","httpStatus":null,"severity":"error","filePath":"core/ledger/ledgermgmt/ledger_mgmt.go","lineNumber":32,"sourceCode":"\t\"github.com/hyperledger/fabric-lib-go/common/flogging\"\n\t\"github.com/hyperledger/fabric-lib-go/common/metrics\"\n\t\"github.com/hyperledger/fabric-protos-go-apiv2/common\"\n\tpb \"github.com/hyperledger/fabric-protos-go-apiv2/peer\"\n\t\"github.com/hyperledger/fabric/core/common/ccprovider\"\n\t\"github.com/hyperledger/fabric/core/ledger\"\n\t\"github.com/hyperledger/fabric/core/ledger/cceventmgmt\"\n\t\"github.com/hyperledger/fabric/core/ledger/kvledger\"\n\t\"github.com/hyperledger/fabric/internal/fileutil\"\n\t\"github.com/pkg/errors\"\n)\n\nvar logger = flogging.MustGetLogger(\"ledgermgmt\")\n\n// ErrLedgerAlreadyOpened is thrown by a CreateLedger call if a ledger with the given id is already opened\nvar ErrLedgerAlreadyOpened = errors.New(\"ledger already opened\")\n\n// ErrLedgerMgmtNotInitialized is thrown when ledger mgmt is used before initializing this\nvar ErrLedgerMgmtNotInitialized = errors.New(\"ledger mgmt should be initialized before using\")\n\n// LedgerMgr manages ledgers for all channels\ntype LedgerMgr struct {\n\tcreationLock         sync.Mutex\n\tjoinBySnapshotStatus *pb.JoinBySnapshotStatus\n\n\tlock           sync.Mutex\n\topenedLedgers  map[string]ledger.PeerLedger\n\tledgerProvider ledger.PeerLedgerProvider\n\n\tebMetadataProvider MetadataProvider\n}\n\ntype MetadataProvider interface {\n\tPackageMetadata(ccid string) ([]byte, error)\n}\n\n// Initializer encapsulates all the external dependencies for the ledger module","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/core/ledger/ledgermgmt/ledger_mgmt.go#L14-L50","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Call ledgermgmt.Initialize(initializer) (or construct via NewLedgerMgr per the newer API) before any ledger operation, typically once at peer startup.","Check initialization order in your bootstrap code so no goroutine touches the ledger manager before initialization completes.","In tests, replicate the standard setup (constructLedgerMgrWithTestDefaults / TestLedgerMgmt pattern) before exercising ledger APIs."],"exampleFix":"// before\nlgr, err := ledgermgmt.OpenLedger(chanID) // panics/ErrLedgerMgmtNotInitialized\n\n// after\nledgermgmt.Initialize(initializer) // must run first\nlgr, err := ledgermgmt.OpenLedger(chanID)","handlingStrategy":"type-guard","validationCode":"// ensure ledgermgmt is initialized before any ledger call\nif ledgerMgr == nil || !ledgerMgmtInitialized.Load() {\n    return fmt.Errorf(\"ledger mgmt not initialized; call Initialize/NewLedgerMgr first\")\n}","typeGuard":"func IsLedgerMgmtNotInitialized(err error) bool {\n    return errors.Is(err, ledgermgmt.ErrLedgerMgmtNotInitialized)\n}","tryCatchPattern":"lgr, err := ledgermgmt.OpenLedger(chanID)\nif err != nil {\n    if errors.Is(err, ledgermgmt.ErrLedgerMgmtNotInitialized) {\n        return fmt.Errorf(\"bootstrap bug: ledger mgmt used before initialization: %w\", err)\n    }\n    return err\n}","preventionTips":["Initialize ledger mgmt exactly once at process startup before serving any requests","Use sync.Once or explicit readiness flags around ledgermgmt usage","In tests, mirror the standard setup (test defaults) before exercising ledger APIs","Check initialization logs ('Initialized LedgerMgr') as a startup precondition"],"tags":["go","hyperledger-fabric","sentinel-error","initialization-order"],"backgroundTag":"not-initialized","analyzedSha":"2736b63f8fd5932511d56fe68b7039d15977f7f6","analyzedAt":"2026-09-04T08:52:36.465Z","contentChangedAt":"2026-09-04T08:52:36.465Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}