invalid mapping destination: wildcard index out of range

Error message

invalid mapping destination: wildcard index out of range

What it means

This error wraps ErrInvalidMappingDestination and is returned when a subject mapping destination function (mustache-escaped, e.g. {{Wildcard(2)}}) references a wildcard index greater than the number of wildcards available in the destination token. The library throws it while strictly validating a subject transform via NewSubjectTransformWithStrict, because such a destination could never be resolved at runtime.

Source

Thrown at server/errors.go:238

	ErrMinimumVersionRequired = errors.New("minimum version required")
	// ErrLeafNodeMinVersionRejected is the leafnode protocol error prefix used
	// when rejecting a remote due to leafnodes.min_version.
	ErrLeafNodeMinVersionRejected = errors.New("connection rejected since minimum version required is")

	// ErrInvalidMappingDestination is used for all subject mapping destination errors
	ErrInvalidMappingDestination = errors.New("invalid mapping destination")

	// ErrInvalidMappingDestinationSubject is used to error on a bad transform destination mapping
	ErrInvalidMappingDestinationSubject = fmt.Errorf("%w: invalid transform", ErrInvalidMappingDestination)

	// ErrMappingDestinationNotUsingAllWildcards is used to error on a transform destination not using all of the token wildcards
	ErrMappingDestinationNotUsingAllWildcards = fmt.Errorf("%w: not using all of the token wildcard(s)", ErrInvalidMappingDestination)

	// ErrUnknownMappingDestinationFunction is returned when a subject mapping destination contains an unknown mustache-escaped mapping function.
	ErrUnknownMappingDestinationFunction = fmt.Errorf("%w: unknown function", ErrInvalidMappingDestination)

	// ErrMappingDestinationIndexOutOfRange is returned when the mapping destination function is passed an out of range wildcard index value for one of it's arguments
	ErrMappingDestinationIndexOutOfRange = fmt.Errorf("%w: wildcard index out of range", ErrInvalidMappingDestination)

	// ErrMappingDestinationNotEnoughArgs is returned when the mapping destination function is not passed enough arguments
	ErrMappingDestinationNotEnoughArgs = fmt.Errorf("%w: not enough arguments passed to the function", ErrInvalidMappingDestination)

	// ErrMappingDestinationInvalidArg is returned when the mapping destination function is passed and invalid argument
	ErrMappingDestinationInvalidArg = fmt.Errorf("%w: function argument is invalid or in the wrong format", ErrInvalidMappingDestination)

	// ErrMappingDestinationTooManyArgs is returned when the mapping destination function is passed too many arguments
	ErrMappingDestinationTooManyArgs = fmt.Errorf("%w: too many arguments passed to the function", ErrInvalidMappingDestination)

	// ErrMappingDestinationNotSupportedForImport is returned when you try to use a mapping function other than wildcard in a transform that needs to be reversible (i.e. an import)
	ErrMappingDestinationNotSupportedForImport = fmt.Errorf("%w: the only mapping function allowed for import transforms is {{Wildcard()}}", ErrInvalidMappingDestination)
)

// mappingDestinationErr is a type of subject mapping destination error
type mappingDestinationErr struct {
	token string
	err   error

View on GitHub (pinned to 3a66a489d2)

Solutions

Count the number of wildcard tokens ('*') in the destination subject and ensure every Wildcard(n) index satisfies n <= number of wildcards in that token
Change the destination to include more wildcards, e.g. 'foo.*.*' if you need {{Wildcard(1)}} and {{Wildcard(2)}}
Lower the index in the function argument, e.g. {{Wildcard(0)}} for the first wildcard of the token
Test the mapping with NewSubjectTransformWithStrict in a unit test before deploying account config

Example fix

// before
dest := "outputs.{{Wildcard(2)}}" // only 1 wildcard in token
// after
dest := "outputs.{{Wildcard(0)}}"

Defensive patterns

Strategy: validation

Validate before calling

func validDest(dest string, wildcardCount int) bool {
    for _, m := range regexp.MustCompile(`\{\{Wildcard\((\d+)\)\}`).FindAllStringSubmatch(dest, -1) {
        n, _ := strconv.Atoi(m[1])
        if n > wildcardCount {
            return false
        }
    }
    return true
}

Type guard

func isMappingDestinationErr(err error) bool {
    var mde *mappingDestinationErr
    return errors.As(err, &mde)
}

Try / catch

transform, err := NewSubjectTransformWithStrict(dest)
if err != nil {
    var mde *server.MappingDestinationError
    if errors.As(err, &mde) {
        // log token and fix config
    }
    return err
}

Prevention

Count '*' wildcards in each destination token before assigning Wildcard(n) indexes
Keep destination wildcard indexes zero-based within each token
Add unit tests calling NewSubjectTransformWithStrict for every mapping in account config

When it happens

Trigger: Calling NewSubjectTransformWithStrict with a destination transform whose function argument wildcard index exceeds the wildcard count of that destination token, e.g. destination 'foo.{{Wildcard(2)}}' (only 1 wildcard present, but index 2 requested, i.e. wildcardIndex > npwcs).

Common situations: Hand-writing stream import/export mapping transforms in account config where the destination token has fewer '*' wildcards than the index passed to Wildcard(); copy-pasting a source transform into a destination without adjusting the wildcard index.

Related errors

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