What causes "Error creating block storage root dir [%s]: %s" in hyperledger/fabric?

Create/repair the storage path and grant write access to the peer user (mkdir -p; chown)

Error creating block storage root dir [%s]: %s

Error message

Error creating block storage root dir [%s]: %s

What it means

newBlockfileMgr panics when fileutil.CreateDirIfMissing cannot create (or confirm) the ledger's block storage root directory. Without the dir the block store cannot initialize, so startup is aborted via panic.

Source

Thrown at common/ledger/blkstorage/blockfile_mgr.go:100

			-- Loads from db if exist, if not instantiate a new blockfilesInfo
			-- If blockfilesInfo was loaded from db, compares to FS
			-- If blockfilesInfo and file system are not in sync, syncs blockfilesInfo from FS
	  *) Starts a new file writer
			-- truncates file per blockfilesInfo to remove any excess past last block
	  *) Determines the index information used to find tx and blocks in
	  the file blkstorage
			-- Instantiates a new blockIdxInfo
			-- Loads the index from the db if exists
			-- syncIndex comparing the last block indexed to what is in the FS
			-- If index and file system are not in sync, syncs index from the FS
	  *)  Updates blockchain info used by the APIs
*/
func newBlockfileMgr(id string, conf *Conf, indexConfig *IndexConfig, indexStore *leveldbhelper.DBHandle) (*blockfileMgr, error) {
	logger.Debugf("newBlockfileMgr() initializing file-based block storage for ledger: %s ", id)
	rootDir := conf.getLedgerBlockDir(id)
	_, err := fileutil.CreateDirIfMissing(rootDir)
	if err != nil {
		panic(fmt.Sprintf("Error creating block storage root dir [%s]: %s", rootDir, err))
	}
	mgr := &blockfileMgr{rootDir: rootDir, conf: conf, db: indexStore, cache: newCache(defaultBlockCacheSizeBytes)}

	blockfilesInfo, err := mgr.loadBlkfilesInfo()
	if err != nil {
		panic(fmt.Sprintf("Could not get block file info for current block file from db: %s", err))
	}
	if blockfilesInfo == nil {
		logger.Info(`Getting block information from block storage`)
		if blockfilesInfo, err = constructBlockfilesInfo(rootDir); err != nil {
			panic(fmt.Sprintf("Could not build blockfilesInfo info from block files: %s", err))
		}
		logger.Debugf("Info constructed by scanning the blocks dir = %s", spew.Sdump(blockfilesInfo))
	} else {
		logger.Debug(`Syncing block information from block storage (if needed)`)
		syncBlockfilesInfoFromFS(rootDir, blockfilesInfo)
	}
	err = mgr.saveBlkfilesInfo(blockfilesInfo, true)

View on GitHub (pinned to 2736b63f8f)

Solutions

Create/repair the storage path and grant write access to the peer user (mkdir -p; chown)
Fix peer config (core.yaml fileLedger blockStorage path) or mount a writable volume at that path
If a file occupies the ledger path, remove it or move data to a fresh dir

Example fix

// before: peer config points to read-only path
// fileLedger:
//   storageDirectory: /ro-mount/ledgersData
// after:
// fileLedger:
//   storageDirectory: /var/hyperledger/production/ledgersData

Defensive patterns

Strategy: validation

Validate before calling

rootDir := conf.getLedgerBlockDir(id)
if err := os.MkdirAll(rootDir, 0o755); err != nil {
    return nil, fmt.Errorf("cannot create block storage dir %s: %w", rootDir, err)
}

Try / catch

defer func() {
    if r := recover(); r != nil {
        err = fmt.Errorf("block storage init failed: %v", r)
    }
}()

Prevention

Verify the configured fileLedger storage path is writable before peer start (touch test)
Never mount the ledger volume read-only
Ensure the path is a directory, not a file, and parent dirs exist
Provision disk space before startup

When it happens

Trigger: CreateDirIfMissing returns an error: parent path does not exist and cannot be created, permission denied, path exists as a file, or filesystem is read-only/full.

Common situations: Wrong peer configuration for fileLedger storage path; read-only container rootfs or volume; ledger path exists as a regular file left by a bad restore; running peer as a user without write access to /var/hyperledger.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

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