nats-io/nats-server · error

error creating store for stream

Error message

error creating store for stream

What it means

This is a generalized JetStream API error returned to clients when a stream's backing message store could not be created. The server deliberately replaces the specific store error (detected via IsNatsErr(err, JSStreamStoreFailedF)) with this generic message so internal storage details are not leaked to clients; the original cause is attached via Unless(err).

Source

Thrown at server/jetstream_api.go:419

const JSMaxNameLen = 255

// JSDefaultRequestQueueLimit is the default number of entries that we will
// put on the global request queue before we react.
const JSDefaultRequestQueueLimit = 10_000

// Responses for API calls.

// ApiResponse is a standard response from the JetStream JSON API
type ApiResponse struct {
	Type  string    `json:"type"`
	Error *ApiError `json:"error,omitempty"`
}

const JSApiSystemResponseType = "io.nats.jetstream.api.v1.system_response"

// When passing back to the clients generalize store failures.
var (
	errStreamStoreFailed   = errors.New("error creating store for stream")
	errConsumerStoreFailed = errors.New("error creating store for consumer")
)

// ToError checks if the response has a error and if it does converts it to an error avoiding
// the pitfalls described by https://yourbasic.org/golang/gotcha-why-nil-error-not-equal-nil/
func (r *ApiResponse) ToError() error {
	if r.Error == nil {
		return nil
	}

	return r.Error
}

const JSApiOverloadedType = "io.nats.jetstream.api.v1.system_overloaded"

// ApiPaged includes variables used to create paged responses from the JSON API
type ApiPaged struct {
	Total  int `json:"total"`

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Check server logs for the underlying store failure warning ('Stream create failed for ...') to find the real cause.
2. Verify JetStream storage directory exists, is writable, and has free disk space.
3. Validate StreamConfig storage/filesystem settings before retrying creation.
4. If clustered, ensure a peer with healthy storage can host the stream and retry after fixing the node.

Example fix

// before
sc := &nats.StreamConfig{Name: "ORDERS", Storage: nats.FileStorage} // disk full
js.AddStream(sc)
// after
if err := checkDiskSpace(cfg.StoreDir); err != nil { return err }
sc := &nats.StreamConfig{Name: "ORDERS", Storage: nats.FileStorage}
if _, err := js.AddStream(sc); err != nil {
    var apiErr *nats.APIError
    if errors.As(err, &apiErr) && apiErr.Description == "error creating store for stream" {
        // inspect server logs for root cause
    }
}

if _, err := os.Stat(storeDir); err != nil { return err }
if err := checkWritable(storeDir); err != nil { return err }
if err := checkFreeDisk(storeDir, minFreeBytes); err != nil { return err }

func isStreamStoreFailed(err error) bool {
    var apiErr *nats.APIError
    return errors.As(err, &apiErr) && apiErr.Description == "error creating store for stream"
}

if _, err := js.AddStream(cfg); err != nil {
    if isStreamStoreFailed(err) {
        // root cause only in server logs: check storage dir, disk space, FD limits
        return retryAfterStorageCheck(cfg)
    }
    return err
}

When it happens

Trigger: A stream create request ($JS.API.STREAM.CREATE.*) fails while the server instantiates the storage for the stream, matching JSStreamStoreFailedF; handled both in the direct API path (jetstream_api.go) and the clustered path (jetstream_cluster.go).

Common situations: Disk full or unwritable storage directory (FileStore), bad StorageType/retention config, insufficient file descriptors, or storage backend initialization failure on node(s) in a cluster.

Related errors

• error creating store for consumer
• create retained messages stream for account %q: %v
• storage type can not be updated
• JS_STREAM_OFFLINE
• JS_ERR_GENERIC

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