nats-io/nats-server · error

error creating store for consumer

Error message

error creating store for consumer

What it means

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).

Solutions

1. Inspect server logs for 'Consumer create failed for ...' to get the underlying store error.
2. Free disk space / fix permissions on the JetStream storage directory.
3. Verify the target stream is healthy (not sealed/corrupt) before creating consumers.
4. Retry consumer creation after repairing storage; if clustered, ensure a healthy peer hosts the stream.

Example fix

// before
js.AddConsumer("ORDERS", cfg) // fails: storage dir full, error generalized
// after
if err := ensureWritable(cfg.StoreDir); err != nil { return err }
cc, err := js.AddConsumer("ORDERS", cfg)
if err != nil {
    var apiErr *nats.APIError
    if errors.As(err, &apiErr) {
        log.Printf("consumer create failed: %v (cause: %v)", apiErr, apiErr.Underlying())
    }
}

if _, err := js.StreamInfo(streamName); err != nil { return err } // stream must be healthy first
if err := checkWritable(storeDir); err != nil { return err }

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

if _, err := js.AddConsumer(stream, cfg); err != nil {
    if isConsumerStoreFailed(err) {
        log.Printf("consumer store failed; check server logs and storage health")
        return retryAfterStorageCheck(stream, cfg)
    }
    return err
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• error creating store for stream
• storage type can not be updated
• 10005
• 10062
• 10069

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

Appendix: source

Thrown at server/jetstream_api.go:420

// 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"`
	Offset int `json:"offset"`

View on GitHub (pinned to 3a66a489d2)