nats-io/nats-server · error

could not register snapshot delivery interest for %q: %w

Error message

could not register snapshot delivery interest for %q: %w

What it means

Server-side snapshot (stream/consumer backup) setup error. Before delivering a snapshot the server registers a notification interest on req.DeliverSubject via the account's subscription list; if registration fails (interest system error), the snapshot is aborted and this wrapped error is returned.

Source

Thrown at server/jetstream_api.go:4619

	chunkSize = min(max(1024, chunkSize), 1024*1024) // Clamp within 1KiB to 1MiB
	wndSize = min(max(1024, wndSize), 32*1024*1024)  // Clamp within 1KiB to 32MiB
	wndSize = max(wndSize, chunkSize)                // Guarantee at least one chunk
	maxInflight := wndSize / chunkSize               // Between 1 and 32,768

	// Setup for the chunk stream.
	reply := req.DeliverSubject
	r := sr.Reader
	defer r.Close()

	// In case we run into an error, this allows subscription callbacks
	// to not sit and block endlessly.
	done := make(chan struct{})
	defer close(done)

	// Check interest for the snapshot deliver subject.
	inch := make(chan bool, 1)
	if err := acc.sl.RegisterNotification(req.DeliverSubject, inch); err != nil {
		return fmt.Errorf("could not register snapshot delivery interest for %q: %w", req.DeliverSubject, err)
	}
	defer acc.sl.ClearNotification(req.DeliverSubject, inch)
	hasInterest := <-inch
	if !hasInterest {
		// Allow 2 seconds or so for interest to show up.
		select {
		case <-inch:
		case <-time.After(2 * time.Second):
		}
	}

	// One slot per chunk. Each chunk read takes a slot, each ack will
	// replace it. Smooths out in-flight number of chunks.
	slots := make(chan struct{}, maxInflight)
	for range maxInflight {
		slots <- struct{}{}
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Retry the snapshot with a fresh, unique DeliverSubject
2. Check server logs and subscription-list state for interest registration errors; investigate leafnode/gateway interest propagation
3. Ensure the snapshot consumer subscribes to the deliver subject promptly so interest exists

deliverSubject := nats.NewInbox() // fresh unique subject per snapshot attempt

err := doSnapshot(req)
if err != nil && strings.Contains(err.Error(), "could not register snapshot delivery interest") {
	req.DeliverSubject = nats.NewInbox()
	return doSnapshot(req) // retry with fresh subject
}

When it happens

Trigger: Calling stream/consumer snapshot/backup API (jsm stream backup / consumer backup) where acc.sl.RegisterNotification fails for the requested DeliverSubject.

Common situations: Interest registration failures under heavy subscription churn or with interest-mode issues in leafnode/gateway setups; malformed or colliding deliver subjects from custom snapshot tooling.

Related errors

• error creating store for stream
• error creating store for consumer
• JS_STREAM_OFFLINE
• JS_ERR_GENERIC
• no interest

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