{"record":{"id":"40c461af6fbd7026","repo":"nats-io/nats-server","slug":"invalid-mapping-destination-wildcard-index-out-of","errorCode":null,"errorMessage":"invalid mapping destination: wildcard index out of range","messagePattern":"invalid mapping destination: wildcard index out of range","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/errors.go","lineNumber":238,"sourceCode":"\tErrMinimumVersionRequired = errors.New(\"minimum version required\")\n\t// ErrLeafNodeMinVersionRejected is the leafnode protocol error prefix used\n\t// when rejecting a remote due to leafnodes.min_version.\n\tErrLeafNodeMinVersionRejected = errors.New(\"connection rejected since minimum version required is\")\n\n\t// ErrInvalidMappingDestination is used for all subject mapping destination errors\n\tErrInvalidMappingDestination = errors.New(\"invalid mapping destination\")\n\n\t// ErrInvalidMappingDestinationSubject is used to error on a bad transform destination mapping\n\tErrInvalidMappingDestinationSubject = fmt.Errorf(\"%w: invalid transform\", ErrInvalidMappingDestination)\n\n\t// ErrMappingDestinationNotUsingAllWildcards is used to error on a transform destination not using all of the token wildcards\n\tErrMappingDestinationNotUsingAllWildcards = fmt.Errorf(\"%w: not using all of the token wildcard(s)\", ErrInvalidMappingDestination)\n\n\t// ErrUnknownMappingDestinationFunction is returned when a subject mapping destination contains an unknown mustache-escaped mapping function.\n\tErrUnknownMappingDestinationFunction = fmt.Errorf(\"%w: unknown function\", ErrInvalidMappingDestination)\n\n\t// ErrMappingDestinationIndexOutOfRange is returned when the mapping destination function is passed an out of range wildcard index value for one of it's arguments\n\tErrMappingDestinationIndexOutOfRange = fmt.Errorf(\"%w: wildcard index out of range\", ErrInvalidMappingDestination)\n\n\t// ErrMappingDestinationNotEnoughArgs is returned when the mapping destination function is not passed enough arguments\n\tErrMappingDestinationNotEnoughArgs = fmt.Errorf(\"%w: not enough arguments passed to the function\", ErrInvalidMappingDestination)\n\n\t// ErrMappingDestinationInvalidArg is returned when the mapping destination function is passed and invalid argument\n\tErrMappingDestinationInvalidArg = fmt.Errorf(\"%w: function argument is invalid or in the wrong format\", ErrInvalidMappingDestination)\n\n\t// ErrMappingDestinationTooManyArgs is returned when the mapping destination function is passed too many arguments\n\tErrMappingDestinationTooManyArgs = fmt.Errorf(\"%w: too many arguments passed to the function\", ErrInvalidMappingDestination)\n\n\t// 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)\n\tErrMappingDestinationNotSupportedForImport = fmt.Errorf(\"%w: the only mapping function allowed for import transforms is {{Wildcard()}}\", ErrInvalidMappingDestination)\n)\n\n// mappingDestinationErr is a type of subject mapping destination error\ntype mappingDestinationErr struct {\n\ttoken string\n\terr   error","sourceCodeStart":220,"sourceCodeEnd":256,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/errors.go#L220-L256","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before\ndest := \"outputs.{{Wildcard(2)}}\" // only 1 wildcard in token\n// after\ndest := \"outputs.{{Wildcard(0)}}\"","handlingStrategy":"validation","validationCode":"func validDest(dest string, wildcardCount int) bool {\n    for _, m := range regexp.MustCompile(`\\{\\{Wildcard\\((\\d+)\\)\\}`).FindAllStringSubmatch(dest, -1) {\n        n, _ := strconv.Atoi(m[1])\n        if n > wildcardCount {\n            return false\n        }\n    }\n    return true\n}","typeGuard":"func isMappingDestinationErr(err error) bool {\n    var mde *mappingDestinationErr\n    return errors.As(err, &mde)\n}","tryCatchPattern":"transform, err := NewSubjectTransformWithStrict(dest)\nif err != nil {\n    var mde *server.MappingDestinationError\n    if errors.As(err, &mde) {\n        // log token and fix config\n    }\n    return err\n}","preventionTips":["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"],"tags":["jetstream","subject-transform","config-validation"],"backgroundTag":"invalid-subject-mapping-destination","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}