What causes "stream catching up" in nats-io/nats-server?

Wait for catch-up to finish and re-run the health check; this is normally transient

stream catching up

Error message

stream catching up

What it means

Returned by jetStream.isStreamHealthy when the replicated stream is still catching up: its Raft node is replaying entries (e.g. after a restart, snapshot restore, or lag) and is not yet up to date with the group. This is a transient 'not yet current' state rather than a fault.

Source

Thrown at server/jetstream_cluster.go:1066

	case msetNode == nil:
		// Can happen when the stream's node is not yet initialized.
		return errors.New("stream node missing")

	case node != msetNode:
		s.Warnf("Detected stream cluster node skew '%s > %s'", acc.GetName(), streamName)
		return errors.New("cluster node skew detected")

	case nrgWerr != nil:
		return fmt.Errorf("node write error: %v", nrgWerr)

	case streamWerr != nil:
		return fmt.Errorf("stream write error: %v", streamWerr)

	case !mset.isMonitorRunning():
		return errors.New("monitor goroutine not running")

	case mset.isCatchingUp():
		return errors.New("stream catching up")

	case !node.Healthy():
		return errors.New("group node unhealthy")

	default:
		return nil
	}
}

// isConsumerHealthy will determine if the consumer is up to date.
// For R1 it will make sure the consunmer is present on this server.
func (js *jetStream) isConsumerHealthy(mset *stream, consumer string, ca *consumerAssignment) error {
	js.mu.RLock()
	if ca != nil && ca.unsupported != nil {
		js.mu.RUnlock()
		return nil
	}
	if mset == nil {

View on GitHub (pinned to 3a66a489d2)

Solutions

Wait for catch-up to finish and re-run the health check; this is normally transient
Reduce lag sources: keep the server connected and disk I/O healthy; consider snapshotting/compaction
If catch-up never completes, check raft group connectivity and restart the lagging node

Defensive patterns

Strategy: retry

Try / catch

if err != nil && strings.Contains(err.Error(), "stream catching up") {
    // expected after restarts/partitions; poll until caught up
    time.Sleep(backoff)
    return healthcheck()
}

Prevention

Expect catching-up errors after server restarts and treat them as non-fatal
Keep large streams on healthy disks so log replay is fast
Use jsz to observe raft lag rather than failing hard on transient catch-up

When it happens

Trigger: HEALTHCHECK on a server whose raft node is replaying the log / installing a snapshot / catching up after downtime, detected via mset.isCatchingUp().

Common situations: Restarted or newly added replica behind the leader; slow disk replaying a large stream; network partition recovery where the follower must resync.

Related errors

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