nats-io/nats-server · error

could not create consumer directory - %v

Error message

could not create consumer directory - %v

What it means

Returned when os.MkdirAll fails to create the consumer's data directory (<StoreDir>/msgs/consumers/<name>) with default directory permissions. Without this directory the file-backed consumer store cannot be initialized, so creation aborts and the error wraps the OS-level cause (%v).

Source

Thrown at server/filestore.go:13350

		return nil, ErrStoreClosed
	}
	if cfg == nil || name == _EMPTY_ {
		return nil, fmt.Errorf("bad consumer config")
	}

	// We now allow overrides from a stream being a filestore type and forcing a consumer to be memory store.
	if cfg.MemoryStorage {
		// Create directly here.
		o := &consumerMemStore{ms: fs, name: name, cfg: *cfg}
		if err := fs.AddConsumer(o); err != nil {
			return nil, err
		}
		return o, nil
	}

	odir := filepath.Join(fs.fcfg.StoreDir, consumerDir, name)
	if err := os.MkdirAll(odir, defaultDirPerms); err != nil {
		return nil, fmt.Errorf("could not create consumer directory - %v", err)
	}
	csi := &FileConsumerInfo{Name: name, Created: created, ConsumerConfig: *cfg}
	o := &consumerFileStore{
		fs:   fs,
		cfg:  csi,
		prf:  fs.prf,
		name: name,
		odir: odir,
		ifn:  filepath.Join(odir, consumerState),
	}
	key := sha256.Sum256([]byte(fs.cfg.Name + "/" + name))
	hh, err := highwayhash.NewDigest64(key[:])
	if err != nil {
		return nil, fmt.Errorf("could not create hash: %v", err)
	}
	o.hh = hh

	// Check for encryption.

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Read the wrapped OS error: fix permissions (chown/chmod) or free disk space on StoreDir.
2. Check that the target path is not occupied by a regular file; remove or rename it.
3. Ensure the filesystem is writable (not mounted ro) and no security module blocks mkdir.
4. Verify StoreDir configuration points to the intended writable directory.

Example fix

// before
$ nats-server with StoreDir /srv/jetstream (read-only mount)
// after
$ sudo mount -o remount,rw /srv && sudo chown -R nats:nats /srv/jetstream

// pre-check writability of the store dir
fi, err := os.Stat(storeDir)
if err != nil || !fi.IsDir() {
    return fmt.Errorf("StoreDir missing or not a directory: %v", err)
}
if err := syscall.Access(storeDir, os.O_RDWR); err != nil {
    return fmt.Errorf("StoreDir not writable: %v", err)
}

if err != nil {
    var pe *fs.PathError
    if errors.As(err, &pe) {
        log.Printf("consumer dir creation failed: %s: %v", pe.Path, pe.Err)
    }
}

When it happens

Trigger: Creating a file-backed consumer where MkdirAll on the consumer directory fails — disk full, permission denied, read-only filesystem, or a file exists at the target path.

Common situations: StoreDir on a read-only or full volume; wrong ownership after restoring data as another user; a regular file named like the consumer directory left by a bad restore; SELinux/AppArmor restrictions.

Related errors

• could not create storage directory - %v
• storage directory is not writable
• could not create message storage directory - %v
• could not create consumer storage directory - %v
• Error creating msg block file: %v

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