What causes "stream configuration for republish from '%s' to '%s': %w" in nats-io/nats-server?

Make the RePublish.Destination have the same number of tokens/wildcards as the Source.

stream configuration for republish from '%s' to '%s': %w

Error message

stream configuration for republish from '%s' to '%s': %w

What it means

During stream setup/update, the RePublish configuration is compiled into a SubjectTransform via NewSubjectTransform; a failure is wrapped as "stream configuration for republish from '%s' to '%s'". It means the RePublish.Source or RePublish.Destination subject in the stream config is not a valid transformable subject.

Source

Thrown at server/stream.go:2862

			mset.subscribeToMirrorDirect()
		} else {
			mset.unsubscribeToMirrorDirect()
		}
	}

	// Check for changes to RePublish.
	if cfg.RePublish != nil {
		// Empty same as all.
		if cfg.RePublish.Source == _EMPTY_ {
			cfg.RePublish.Source = fwcs
		}
		if cfg.RePublish.Destination == _EMPTY_ {
			cfg.RePublish.Destination = fwcs
		}
		tr, err := NewSubjectTransform(cfg.RePublish.Source, cfg.RePublish.Destination)
		if err != nil {
			mset.mu.Unlock()
			return fmt.Errorf("stream configuration for republish from '%s' to '%s': %w", cfg.RePublish.Source, cfg.RePublish.Destination, err)
		}
		// Assign our transform for republishing.
		mset.tr = tr
	} else {
		mset.tr = nil
	}

	// Check for changes to subject transform
	if ocfg.SubjectTransform == nil && cfg.SubjectTransform != nil {
		tr, err := NewSubjectTransform(cfg.SubjectTransform.Source, cfg.SubjectTransform.Destination)
		if err != nil {
			mset.mu.Unlock()
			return fmt.Errorf("stream configuration for subject transform from '%s' to '%s': %w", cfg.SubjectTransform.Source, cfg.SubjectTransform.Destination, err)
		}
		mset.itr = tr
	} else if ocfg.SubjectTransform != nil && cfg.SubjectTransform != nil &&
		(ocfg.SubjectTransform.Source != cfg.SubjectTransform.Source || ocfg.SubjectTransform.Destination != cfg.SubjectTransform.Destination) {
		tr, err := NewSubjectTransform(cfg.SubjectTransform.Source, cfg.SubjectTransform.Destination)

View on GitHub (pinned to 3a66a489d2)

Solutions

Make the RePublish.Destination have the same number of tokens/wildcards as the Source.
Validate subjects (syntax and wildcard placement) before submitting the config.
Remove RePublish or set it to nil if republishing is not required.

Example fix

// before
RePublish: &RePublish{Source: "foo.*", Destination: "bar.*.*"}
// after
RePublish: &RePublish{Source: "foo.*", Destination: "bar.*"}

Defensive patterns

Strategy: validation

Validate before calling

if rp := cfg.RePublish; rp != nil {
    if err := validTransformPair(rp.Source, rp.Destination); err != nil { return err }
}

Try / catch

if err != nil && strings.Contains(err.Error(), "republish from") { /* fix RePublish.Source/Destination */ }

Prevention

Use the same number of wildcard tokens in Source and Destination.
Test transforms on a scratch stream before production updates.

When it happens

Trigger: UpdateStream/CreateStream with StreamConfig.RePublish whose Source/Destination cannot be compiled, e.g. RePublish.Source with invalid wildcards or a Destination incompatible with the source's token count.

Common situations: Destination with different number of wildcard tokens than Source (e.g. Source 'foo.*' -> Destination 'bar.*.*'), invalid subject characters, or empty/whitespace source.

Related errors

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