{"record":{"id":"e51bf84d8efb49f4","repo":"nats-io/nats-server","slug":"error-creating-store-for-stream","errorCode":null,"errorMessage":"error creating store for stream","messagePattern":"error creating store for stream","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/jetstream_api.go","lineNumber":419,"sourceCode":"const JSMaxNameLen = 255\n\n// JSDefaultRequestQueueLimit is the default number of entries that we will\n// put on the global request queue before we react.\nconst JSDefaultRequestQueueLimit = 10_000\n\n// Responses for API calls.\n\n// ApiResponse is a standard response from the JetStream JSON API\ntype ApiResponse struct {\n\tType  string    `json:\"type\"`\n\tError *ApiError `json:\"error,omitempty\"`\n}\n\nconst JSApiSystemResponseType = \"io.nats.jetstream.api.v1.system_response\"\n\n// When passing back to the clients generalize store failures.\nvar (\n\terrStreamStoreFailed   = errors.New(\"error creating store for stream\")\n\terrConsumerStoreFailed = errors.New(\"error creating store for consumer\")\n)\n\n// ToError checks if the response has a error and if it does converts it to an error avoiding\n// the pitfalls described by https://yourbasic.org/golang/gotcha-why-nil-error-not-equal-nil/\nfunc (r *ApiResponse) ToError() error {\n\tif r.Error == nil {\n\t\treturn nil\n\t}\n\n\treturn r.Error\n}\n\nconst JSApiOverloadedType = \"io.nats.jetstream.api.v1.system_overloaded\"\n\n// ApiPaged includes variables used to create paged responses from the JSON API\ntype ApiPaged struct {\n\tTotal  int `json:\"total\"`","sourceCodeStart":401,"sourceCodeEnd":437,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/jetstream_api.go#L401-L437","documentation":"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).","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check server logs for the underlying store failure warning ('Stream create failed for ...') to find the real cause.","Verify JetStream storage directory exists, is writable, and has free disk space.","Validate StreamConfig storage/filesystem settings before retrying creation.","If clustered, ensure a peer with healthy storage can host the stream and retry after fixing the node."],"exampleFix":"// before\nsc := &nats.StreamConfig{Name: \"ORDERS\", Storage: nats.FileStorage} // disk full\njs.AddStream(sc)\n// after\nif err := checkDiskSpace(cfg.StoreDir); err != nil { return err }\nsc := &nats.StreamConfig{Name: \"ORDERS\", Storage: nats.FileStorage}\nif _, err := js.AddStream(sc); err != nil {\n    var apiErr *nats.APIError\n    if errors.As(err, &apiErr) && apiErr.Description == \"error creating store for stream\" {\n        // inspect server logs for root cause\n    }\n}","handlingStrategy":"type-guard","validationCode":"if _, err := os.Stat(storeDir); err != nil { return err }\nif err := checkWritable(storeDir); err != nil { return err }\nif err := checkFreeDisk(storeDir, minFreeBytes); err != nil { return err }\n","typeGuard":"func isStreamStoreFailed(err error) bool {\n    var apiErr *nats.APIError\n    return errors.As(err, &apiErr) && apiErr.Description == \"error creating store for stream\"\n}","tryCatchPattern":"if _, err := js.AddStream(cfg); err != nil {\n    if isStreamStoreFailed(err) {\n        // root cause only in server logs: check storage dir, disk space, FD limits\n        return retryAfterStorageCheck(cfg)\n    }\n    return err\n}","preventionTips":["Monitor JetStream storage directory disk space and permissions","Validate StreamConfig storage settings before creation","Set log alerts on 'Stream create failed' server warnings","In clusters, ensure at least one healthy peer can host new streams"],"tags":["jetstream","storage","nats-server","stream-creation"],"backgroundTag":"jetstream-store-creation-failed","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}