nats-io/nats-server · error

last sequence mismatch

Error message

last sequence mismatch

What it means

errLastSeqMismatch: a publish carried an expected last sequence (Nats-Expected-Last-Sequence header) that does not equal the stream's current last sequence — an optimistic concurrency check. In clustered catch-up code the same sentinel indicates raft stream divergence and triggers the cluster-reset recovery path.

Source

Thrown at server/stream.go:6373

	hdr = removeHeaderStatusIfPresent(hdr)
	if mt, traceOnly := c.isMsgTraceEnabled(); mt != nil {
		// If message is delivered, we need to disable the message trace headers
		// to prevent a trace event to be generated when a stored message
		// is delivered to a consumer and routed.
		if !traceOnly {
			hdr = setHeader(MsgTraceDest, MsgTraceDestDisabled, hdr)
		}
		// This will add the jetstream event while in the client read loop.
		// Since the event will be updated in a different go routine, the
		// tracing object will have a separate reference to the JS trace
		// object.
		mt.addJetStreamEvent(mset.name())
	}
	mset.queueInbound(mset.msgs, subject, reply, hdr, msg, nil, c.pa.trace)
}

var (
	errLastSeqMismatch   = errors.New("last sequence mismatch")
	errMsgIdDuplicate    = errors.New("msgid is duplicate")
	errStreamClosed      = errors.New("stream closed")
	errInvalidMsgHandler = errors.New("undefined message handler")
	errStreamMismatch    = errors.New("expected stream does not match")
	errMsgTTLDisabled    = errors.New("message TTL disabled")
)

// processJetStreamMsg is where we try to actually process the stream msg.
// needIsolation should be false only if the caller already holds isolateMu
// across a whole atomic batch; mset.mu must NOT be held by the caller.
func (mset *stream) processJetStreamMsg(subject, reply string, hdr, msg []byte, lseq uint64, ts int64, mt *msgTrace, sourced bool, needIsolation bool) error {
	return mset.processJetStreamMsgWithBatch(subject, reply, hdr, msg, lseq, ts, mt, sourced, needIsolation, nil)
}

func (mset *stream) processJetStreamMsgWithBatch(subject, reply string, hdr, msg []byte, lseq uint64, ts int64, mt *msgTrace, sourced bool, needIsolation bool, fastBatch *FastBatch) (retErr error) {
	if mt != nil {
		// Only the leader/standalone will have mt!=nil. On exit, send the
		// message trace event.

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Fetch the current stream state and retry with the correct expected sequence
2. Use Nats-Expected-Last-Subject-Sequence if only per-subject ordering matters
3. For cluster occurrences, ensure raft/meta health and let the server reset or catch up the stream

When it happens

Trigger: Thrown at server/stream.go:6373 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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