What causes "start sequence can not be updated" in nats-io/nats-server?

Delete the consumer and recreate it with the new OptStartSeq.

start sequence can not be updated

Error message

start sequence can not be updated

What it means

OptStartSeq (optional starting sequence for DeliverByStartSequence) is treated as immutable: once a consumer is created with a starting sequence, it cannot be changed. checkNewConsumerConfig rejects updates where cfg.OptStartSeq != ncfg.OptStartSeq.

Source

Thrown at server/consumer.go:2549

		return nil
	}
	// Something different, so check since we only allow certain things to be updated.
	if cfg.DeliverPolicy != ncfg.DeliverPolicy {
		return errors.New("deliver policy can not be updated")
	}
	if cfg.MemoryStorage != ncfg.MemoryStorage {
		return errors.New("storage type can not be updated")
	}
	// Direct and Sourcing classify the consumer for its whole lifetime, which the
	// stream relies on when walking its consumer list, so they can not change.
	if cfg.Direct != ncfg.Direct {
		return errors.New("direct can not be updated")
	}
	if cfg.Sourcing != ncfg.Sourcing {
		return errors.New("sourcing can not be updated")
	}
	if cfg.OptStartSeq != ncfg.OptStartSeq {
		return errors.New("start sequence can not be updated")
	}
	if cfg.OptStartTime != nil && ncfg.OptStartTime != nil {
		// Both have start times set, compare them directly:
		if !cfg.OptStartTime.Equal(*ncfg.OptStartTime) {
			return errors.New("start time can not be updated")
		}
	} else if cfg.OptStartTime != nil || ncfg.OptStartTime != nil {
		// At least one start time is set and the other is not
		return errors.New("start time can not be updated")
	}
	if cfg.AckPolicy != ncfg.AckPolicy {
		return errors.New("ack policy can not be updated")
	}
	if cfg.ReplayPolicy != ncfg.ReplayPolicy {
		return errors.New("replay policy can not be updated")
	}
	if cfg.Heartbeat != ncfg.Heartbeat {
		return errors.New("heart beats can not be updated")

View on GitHub (pinned to 3a66a489d2)

Solutions

Delete the consumer and recreate it with the new OptStartSeq.
Create a new durable consumer for the new starting sequence.
Remove OptStartSeq from the update so it matches the existing value.
Use an advisory/management flow that recreates consumers on start-position changes.

Example fix

// before
js.UpdateConsumer(stream, &nats.ConsumerConfig{Durable: "replay", OptStartSeq: 42})
// after
js.DeleteConsumer(stream, "replay")
js.AddConsumer(stream, &nats.ConsumerConfig{Durable: "replay", OptStartSeq: 100})

Defensive patterns

Strategy: validation

Validate before calling

if existing.OptStartSeq != desired.OptStartSeq {
	return errors.New("start sequence cannot be updated; recreate the consumer")
}

Prevention

Freeze OptStartSeq in deployment artifacts; do not recompute per deploy
Recreate replay consumers when the start sequence must move
Only update mutable fields (e.g. ack wait, max deliver) on existing durables

When it happens

Trigger: js.UpdateConsumer on an existing durable created with OptStartSeq set (DeliverPolicy DeliverByStartSequence) where the update supplies a different sequence number, or adds/removes OptStartSeq.

Common situations: Resetting a consumer to an earlier sequence after a data incident; automation recomputing the start sequence on each deploy; repointing a replay consumer at a different starting point.

Related errors

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