{"record":{"id":"c70c7f1251bb0180","repo":"nats-io/nats-server","slug":"error-creating-store-for-consumer","errorCode":null,"errorMessage":"error creating store for consumer","messagePattern":"error creating store for consumer","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/jetstream_api.go","lineNumber":420,"sourceCode":"\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\"`\n\tOffset int `json:\"offset\"`","sourceCodeStart":402,"sourceCodeEnd":438,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/jetstream_api.go#L402-L438","documentation":"This is the consumer counterpart of errStreamStoreFailed: a generalized JetStream API error returned when a consumer's backing store could not be created. The specific storage error (matched via IsNatsErr with JSConsumerStoreFailedF/ErrF) is replaced with this generic message before building the API error response, with the original error preserved via Unless(err).","triggerScenarios":"A consumer create request ($JS.API.CONSUMER.CREATE.*) fails while instantiating consumer storage, in both the direct API handler and the clustered handler (jetstream_cluster.go ~line 6941).","commonSituations":"Disk exhaustion or I/O errors in the stream's storage directory, corrupted stream state blocking consumer state files, permission problems, or resource limits on the hosting node.","solutions":["Inspect server logs for 'Consumer create failed for ...' to get the underlying store error.","Free disk space / fix permissions on the JetStream storage directory.","Verify the target stream is healthy (not sealed/corrupt) before creating consumers.","Retry consumer creation after repairing storage; if clustered, ensure a healthy peer hosts the stream."],"exampleFix":"// before\njs.AddConsumer(\"ORDERS\", cfg) // fails: storage dir full, error generalized\n// after\nif err := ensureWritable(cfg.StoreDir); err != nil { return err }\ncc, err := js.AddConsumer(\"ORDERS\", cfg)\nif err != nil {\n    var apiErr *nats.APIError\n    if errors.As(err, &apiErr) {\n        log.Printf(\"consumer create failed: %v (cause: %v)\", apiErr, apiErr.Underlying())\n    }\n}","handlingStrategy":"type-guard","validationCode":"if _, err := js.StreamInfo(streamName); err != nil { return err } // stream must be healthy first\nif err := checkWritable(storeDir); err != nil { return err }\n","typeGuard":"func isConsumerStoreFailed(err error) bool {\n    var apiErr *nats.APIError\n    return errors.As(err, &apiErr) && apiErr.Description == \"error creating store for consumer\"\n}","tryCatchPattern":"if _, err := js.AddConsumer(stream, cfg); err != nil {\n    if isConsumerStoreFailed(err) {\n        log.Printf(\"consumer store failed; check server logs and storage health\")\n        return retryAfterStorageCheck(stream, cfg)\n    }\n    return err\n}","preventionTips":["Keep the stream's storage directory healthy (space, permissions, no corruption)","Verify the target stream exists and is online before adding consumers","Alert on 'Consumer create failed' server warnings","Repair or recreate corrupted streams before consumer creation"],"tags":["jetstream","storage","consumer","nats-server"],"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"}