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

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)

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

• storage type can not be updated
• error creating store for stream
• max_request_batch must be set if it's JetStream limits are s
• consumer name can not contain '.', '*', '>', '\', '/'
• consumer durable name can not contain '.', '*', '>', '\', '/

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