{"record":{"id":"8f53d88348c51a20","repo":"hyperledger/fabric","slug":"failed-to-create-ledger-directory-s","errorCode":null,"errorMessage":"failed to create ledger directory: %s","messagePattern":"failed to create ledger directory: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/ledger/blkstorage/blockstore_provider.go","lineNumber":79,"sourceCode":"\tdbConf := &leveldbhelper.Conf{\n\t\tDBPath:         conf.getIndexDir(),\n\t\tExpectedFormat: dataFormatVersion(indexConfig),\n\t}\n\n\tp, err := leveldbhelper.NewProvider(dbConf)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tdirPath := conf.getChainsDir()\n\tif _, err := os.Stat(dirPath); err != nil {\n\t\tif !os.IsNotExist(err) { // NotExist is the only permitted error type\n\t\t\treturn nil, errors.Wrapf(err, \"failed to read ledger directory %s\", dirPath)\n\t\t}\n\n\t\tlogger.Info(\"Creating new file ledger directory at\", dirPath)\n\t\tif err = os.MkdirAll(dirPath, 0o755); err != nil {\n\t\t\treturn nil, errors.Wrapf(err, \"failed to create ledger directory: %s\", dirPath)\n\t\t}\n\t}\n\n\tstats := newStats(metricsProvider)\n\treturn &BlockStoreProvider{conf, indexConfig, p, stats}, nil\n}\n\n// Open opens a block store for given ledgerid.\n// If a blockstore is not existing, this method creates one\n// This method should be invoked only once for a particular ledgerid\nfunc (p *BlockStoreProvider) Open(ledgerid string) (*BlockStore, error) {\n\tindexStoreHandle := p.leveldbProvider.GetDBHandle(ledgerid)\n\treturn newBlockStore(ledgerid, p.conf, p.indexConfig, indexStoreHandle, p.stats)\n}\n\n// ImportFromSnapshot initializes blockstore from a previously generated snapshot\n// Any failure during bootstrapping the blockstore may leave the partial loaded data\n// on disk. The consumer, such as peer is expected to keep track of failures and cleanup the","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/common/ledger/blkstorage/blockstore_provider.go#L61-L97","documentation":"NewProvider in the blkstorage package creates the ledger's block storage directory when it does not exist. If os.MkdirAll(dirPath, 0o755) fails, the underlying OS error is wrapped with \"failed to create ledger directory: %s\" and provider construction is aborted. This means the process cannot obtain the directory needed to store block files.","triggerScenarios":"Calling BootstrapBlockstoreFromSnapshot, New, or openBlockStorage when the parent path of dirPath is not writable, a parent path component is a regular file, the filesystem is full/read-only, or permission bits deny creation (e.g. dirPath exists only partially with wrong ownership).","commonSituations":"peer.fileSystemLedger path pointing into a root-owned or read-only volume (container with mounted volume lacking write permission), Docker/K8s volume mounted with wrong ownership for the peer user, disk full, SELinux/AppArmor denial, or a file existing where a directory component should be.","solutions":["Check the wrapped cause in the error; run mkdir -p on the ledger path as the peer's OS user and chown the directory to that user.","Verify the parent components of the configured ledger path are directories, not files, and the filesystem is not read-only or full (df, mount).","If running in a container, fix the volume mount ownership/mode (e.g. securityContext fsGroup or hostPath permissions).","On SELinux systems, relabel the path (restorecon) or adjust the policy."],"exampleFix":"// before\nledgerPath: \"/var/hyperledger/production/ledgersData/chains\"  // root-owned, peer cannot write\n// after (host)\nsudo mkdir -p /var/hyperledger/production/ledgersData/chains\nsudo chown -R peer:peer /var/hyperledger/production","handlingStrategy":"validation","validationCode":"info, err := os.Stat(dirPath)\nif err == nil {\n    if !info.IsDir() {\n        return fmt.Errorf(\"%s exists and is not a directory\", dirPath)\n    }\n} else if !os.IsNotExist(err) {\n    return err\n}\nif err := syscall.Access(filepath.Dir(dirPath), os.O_RDWR); err != nil {\n    return fmt.Errorf(\"no write permission for parent of %s: %w\", dirPath, err)\n}","typeGuard":null,"tryCatchPattern":"store, err := blkstorage.NewProvider(...)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to create ledger directory\") {\n        // inspect wrapped cause: permissions, parent file, read-only FS\n        return fmt.Errorf(\"ledger dir unusable at %s: %w\", dirPath, err)\n    }\n    return err\n}","preventionTips":["Provision the ledger directory with correct ownership before starting the peer.","In containers, set fsGroup/securityContext so the mounted volume is writable by the peer user.","Monitor disk space and mount read-write on the ledger volume.","Never place a file where a ledger path component is expected."],"tags":["filesystem","ledger","permissions"],"backgroundTag":"mkdir-permission-denied","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"}