nats-io/nats-server · error

stream import prefix can not contain wildcard tokens

Error message

stream import prefix can not contain wildcard tokens

What it means

ErrStreamImportBadPrefix is returned when a stream import prefix contains wildcard tokens. Prefix-based imports prepend the prefix to the publish subject, so the prefix must be a literal subject; wildcards (*, >) would produce invalid subjects and are rejected.

Source

Thrown at server/errors.go:141

	ErrAccountValidation = errors.New("account validation failed")

	// ErrAccountExpired is returned when an account has expired.
	ErrAccountExpired = errors.New("account expired")

	// ErrNoAccountResolver is returned when we attempt an update but do not have an account resolver.
	ErrNoAccountResolver = errors.New("account resolver missing")

	// ErrAccountResolverUpdateTooSoon is returned when we attempt an update too soon to last request.
	ErrAccountResolverUpdateTooSoon = errors.New("account resolver update too soon")

	// ErrAccountResolverSameClaims is returned when same claims have been fetched.
	ErrAccountResolverSameClaims = errors.New("account resolver no new claims")

	// ErrStreamImportAuthorization is returned when a stream import is not authorized.
	ErrStreamImportAuthorization = errors.New("stream import not authorized")

	// ErrStreamImportBadPrefix is returned when a stream import prefix contains wildcards.
	ErrStreamImportBadPrefix = errors.New("stream import prefix can not contain wildcard tokens")

	// ErrStreamImportDuplicate is returned when a stream import is a duplicate of one that already exists.
	ErrStreamImportDuplicate = errors.New("stream import already exists")

	// ErrServiceImportAuthorization is returned when a service import is not authorized.
	ErrServiceImportAuthorization = errors.New("service import not authorized")

	// ErrImportFormsCycle is returned when an import would form a cycle.
	ErrImportFormsCycle = errors.New("import forms a cycle")

	// ErrCycleSearchDepth is returned when we have exceeded our maximum search depth..
	ErrCycleSearchDepth = errors.New("search cycle depth exhausted")

	// ErrClientOrRouteConnectedToGatewayPort represents an error condition when
	// a client or route attempted to connect to the Gateway port.
	ErrClientOrRouteConnectedToGatewayPort = errors.New("attempted to connect to gateway port")

	// ErrWrongGateway represents an error condition when a server receives a connect

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Use a literal (token-by-token, no * or >) prefix string in AddStreamImport
2. If multiple subjects are needed, add one import per subject or map a concrete prefix and subscribe under prefix.<subject>
3. Validate/escape user-supplied prefixes with subjectIsLiteral before calling the API
4. Restructure exports so a single literal prefix can cover the needed subjects

Example fix

// before
acc.AddStreamImport(fooAcc, "to", "foo.*.bar") // wildcard in prefix
// after
acc.AddStreamImport(fooAcc, "to", "foo.one.bar") // literal prefix

if prefix != "" && !subjectIsLiteral(prefix) { return fmt.Errorf("import prefix %q must not contain wildcards", prefix) }

func validImportPrefix(prefix string) bool { return prefix == _EMPTY_ || subjectIsLiteral(prefix) }

if err := acc.AddStreamImport(fromAcc, subject, prefix); err != nil {
	if errors.Is(err, ErrStreamImportBadPrefix) { /* replace wildcard prefix with a literal subject */ }
}

When it happens

Trigger: Calling AddStreamImport with a non-empty prefix argument where subjectIsLiteral(prefix) is false — e.g. AddStreamImport(from, "to", "foo.*") or "pre>" (accounts.go:2720).

Common situations: Trying to fan out an import across multiple subjects with "*" or ">" in the prefix; assuming wildcard prefixes behave like wildcards in subscriptions; copy-pasting subscription subjects into the prefix argument of config or code.

Related errors

• stream import not authorized
• subject has exceeded number of tokens limit
• service missing
• bad service response type
• bad sampling percentage, should be 1-100

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