nats-io/nats-server · warning

stream not found

Error message

stream not found

What it means

Returned by jetStream.isStreamHealthy when acc.lookupStream(streamName) fails during a health check: the assignment says the stream should exist on this server, but the account has no such stream materialized locally. The meta-level assignment and the local stream state are out of sync.

Source

Thrown at server/jetstream_cluster.go:1029

		js.mu.RUnlock()
		return errors.New("stream assignment or group missing")
	}
	// Surface any persisted assignment-level error (e.g. failed create on this
	// peer due to account limits) so the health check reflects the broken state
	// instead of falling through to runtime-only checks.
	if sa.err != nil {
		err := sa.err
		js.mu.RUnlock()
		return fmt.Errorf("stream assignment error: %w", err)
	}
	streamName := sa.Config.Name
	node := sa.Group.node
	js.mu.RUnlock()

	// First lookup stream and make sure its there.
	mset, err := acc.lookupStream(streamName)
	if err != nil {
		return errors.New("stream not found")
	}

	msetNode := mset.raftNode()
	mset.cfgMu.RLock()
	replicas := mset.cfg.Replicas
	mset.cfgMu.RUnlock()
	var nrgWerr error
	if node != nil {
		nrgWerr = node.GetWriteErr()
	}
	streamWerr := mset.getWriteErr()
	switch {
	case replicas <= 1:
		return nil // No further checks for R=1 streams

	case node == nil:
		return errors.New("group node missing")

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Check whether the stream exists via $JS.API.STREAM.INFO.<stream> and on this server via jsz
2. Allow time for the stream create to replicate, then re-run the health check
3. If the assignment is stale (stream deleted), verify the meta group has processed the deletion; restart the server if the state is permanently inconsistent

// Before health-checking, confirm the stream exists
resp, err := nc.Request(fmt.Sprintf("$JS.API.STREAM.INFO.%s", stream), nil, 5*time.Second)
streamExists := err == nil // else the stream truly isn't materialized yet

if err != nil && strings.Contains(err.Error(), "stream not found") {
    // re-check STREAM.INFO; if it now exists, the earlier failure was replication lag
    time.Sleep(backoff)
    return healthcheck()
}

When it happens

Trigger: HEALTHCHECK runs on a peer before the stream create has been applied locally, after local stream deletion, or on a peer that failed/dropped the stream while the meta assignment still lists it.

Common situations: Server still catching up after a restart; stream creation failed on this peer (e.g. account limits) but the assignment remains; timing window during clustered stream creation or removal.

Related errors

• stream assignment or group missing
• group node missing
• cluster node skew detected
• stream node missing
• monitor goroutine not running

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