nats-io/nats-server · error

invalid mirror configuration

Error message

invalid mirror configuration

What it means

setupMirrorConsumer found the stream's mirror configuration unusable — e.g. a mirror added on update after the source was removed, or required fields/outq missing — so the mirror consumer cannot be created. The guard prevents a panic on a stale or malformed mset.cfg.Mirror.

Source

Thrown at server/stream.go:3729

// Setup our mirror consumer.
// Lock should be held.
func (mset *stream) setupMirrorConsumer() error {
	if mset.closed.Load() {
		return errStreamClosed
	}
	if mset.outq == nil {
		return errors.New("outq required")
	}
	// We use to prevent update of a mirror configuration in cluster
	// mode but not in standalone. This is now fixed. However, without
	// rejecting the update, it could be that if the source stream was
	// removed and then later the mirrored stream config changed to
	// remove mirror configuration, this function would panic when
	// accessing mset.cfg.Mirror fields. Adding this protection in case
	// we allow in the future the mirror config to be changed (removed).
	if mset.cfg.Mirror == nil {
		return errors.New("invalid mirror configuration")
	}

	// If this is the first time
	if mset.mirror == nil {
		mset.mirror = &sourceInfo{name: mset.cfg.Mirror.Name}
	} else {
		mset.cancelSourceInfo(mset.mirror)
		mset.mirror.sseq = mset.lseq
	}

	// If we are no longer the leader stop trying.
	if !mset.isLeader() {
		return nil
	}

	mirror := mset.mirror

	// We want to throttle here in terms of how fast we request new consumers,

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Recreate the stream with a complete mirror configuration
2. Ensure the mirror source stream exists and its name is correct
3. Remove the mirror configuration if mirroring is no longer intended

When it happens

Trigger: Thrown at server/stream.go:3729 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/8b2d8e96522395dc. Report an issue: GitHub.