nats-io/nats-server · error

could not create snapshots directory - %v

Error message

could not create snapshots directory - %v

What it means

Before taking a stream snapshot (StreamSnapshot API), the server ensures the snapshots directory under the JetStore dir (snapsDir) exists; if os.MkdirAll fails, the snapshot is aborted with this wrapped OS error. It reflects a filesystem-level problem, not a user config problem.

Source

Thrown at server/stream.go:9325

	s, jsa, err := a.checkForJetStream()
	if err != nil {
		return nil, err
	}
	js := jsa.js
	if js == nil {
		return nil, NewJSNotEnabledForAccountError()
	}

	cfg, apiErr := s.checkStreamCfg(ncfg, a, false)
	if apiErr != nil {
		return nil, apiErr
	}

	sd := filepath.Join(jsa.storeDir, snapsDir)
	if _, err := os.Stat(sd); os.IsNotExist(err) {
		if err := os.MkdirAll(sd, defaultDirPerms); err != nil {
			return nil, fmt.Errorf("could not create snapshots directory - %v", err)
		}
	}
	sdir, err := os.MkdirTemp(sd, "snap-")
	if err != nil {
		return nil, err
	}
	if _, err := os.Stat(sdir); os.IsNotExist(err) {
		if err := os.MkdirAll(sdir, defaultDirPerms); err != nil {
			return nil, fmt.Errorf("could not create snapshots directory - %v", err)
		}
	}
	defer os.RemoveAll(sdir)

	logAndReturnError := func() error {
		a.mu.RLock()
		err := fmt.Errorf("unexpected content (account=%s)", a.Name)
		if a.srv != nil {
			a.srv.Errorf("Stream restore failed due to %v", err)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Check and fix permissions/ownership on the JetStream store directory so the server user can create subdirectories.
2. Verify the filesystem is writable and not full (df / mount).
3. Restart the server with a correct, writable -sd/--store_dir path.

Example fix

// before (container)
volumeMounts: [{mountPath: /data, readOnly: true}]
// after
volumeMounts: [{mountPath: /data, readOnly: false}]
// plus: chown nats:nats /data/jetstream

info, err := os.Stat(storeDir)
if err != nil || !info.IsDir() { return errors.New("jetstream store dir missing or inaccessible") }
if err := syscall.Access(storeDir, syscall.O_RDWR); err != nil { return errors.New("store dir not writable") }

if err != nil && strings.Contains(err.Error(), "could not create snapshots directory") { /* check fs perms/mount and retry */ }

When it happens

Trigger: Calling the stream snapshot API ($JS.API.STREAM.SNAPSHOT.<stream>) when <store_dir>/snaps cannot be created - permissions, read-only filesystem, disk full, or store dir removed out from under a running server.

Common situations: JetStream store directory on a read-only mount, running the server as a user without write permission to the store dir, container with a read-only rootfs, or a custom -sd path with wrong ownership.

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
• could not create consumer directory - %v

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