nats-io/nats-server · critical

could not create consumer storage directory - %v

Error message

could not create consumer storage directory - %v

What it means

Same setup phase as the message directory: the file store creates the per-stream consumers subdirectory (filepath.Join(StoreDir, consumerDir)); os.MkdirAll failure is wrapped with the OS error. The stream store cannot be created without it.

Source

Thrown at server/filestore.go:491

	// If we error before completion make sure to cleanup.
	defer func() {
		if err != nil {
			ats.Unregister()
		}
	}()

	// Set flush in place to AsyncFlush which by default is false.
	fs.fip = !fcfg.AsyncFlush

	// Check if this is a new setup.
	mdir := filepath.Join(fcfg.StoreDir, msgDir)
	odir := filepath.Join(fcfg.StoreDir, consumerDir)
	if err := os.MkdirAll(mdir, defaultDirPerms); err != nil {
		return nil, fmt.Errorf("could not create message storage directory - %v", err)
	}
	if err := os.MkdirAll(odir, defaultDirPerms); err != nil {
		return nil, fmt.Errorf("could not create consumer storage directory - %v", err)
	}

	// Create highway hash for message blocks. Use sha256 of directory as key.
	key := sha256.Sum256([]byte(cfg.Name))
	fs.hh, err = highwayhash.NewDigest64(key[:])
	if err != nil {
		return nil, fmt.Errorf("could not create hash: %v", err)
	}

	keyFile := filepath.Join(fs.fcfg.StoreDir, JetStreamMetaFileKey)
	_, err = os.Stat(keyFile)
	// Either the file should exist (err=nil), or it shouldn't. Any other error is reported.
	if err != nil && !os.IsNotExist(err) {
		return nil, err
	}
	// Make sure we do not have an encrypted store underneath of us but no main key.
	if fs.prf == nil && err == nil {
		return nil, errNoMainKey

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Inspect the wrapped %v OS error for the exact cause
2. Ensure StoreDir is writable by the server process user
3. Remove any regular file occupying the consumers directory path
4. Verify disk space and mount is read-write

Example fix

// before
// $ ls -ld /data/jetstream => dr-xr-xr-x
// after
// $ sudo chmod u+w /data/jetstream && sudo chown nats:nats /data/jetstream
store_dir: "/data/jetstream"

if err := os.MkdirAll(filepath.Join(storeDir, "obs"), 0o755); err != nil {
    return fmt.Errorf("consumer dir pre-check failed: %w", err)
}

if err := startStream(); err != nil {
    if strings.Contains(err.Error(), "could not create consumer storage directory") {
        // fix underlying OS error (perms, space, ro mount), then restart
    }
}

When it happens

Trigger: os.MkdirAll(odir, defaultDirPerms) fails when creating the consumers directory inside StoreDir (server/filestore.go:491).

Common situations: Same class of issues as the msgs directory: permissions, read-only mount, disk full, a file colliding with the consumers directory name.

Understand the failure class

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

Related errors

• could not create storage directory - %v
• storage directory is not writable
• could not create message storage directory - %v
• storage directory is not a directory
• failed to write to temporary file: %w

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/e4f8454b0b46e522. Report an issue: GitHub.