{"record":{"id":"3e792adb612c6727","repo":"nats-io/nats-server","slug":"invalid-mapping-destination-unknown-function","errorCode":null,"errorMessage":"invalid mapping destination: unknown function","messagePattern":"invalid mapping destination: unknown function","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/errors.go","lineNumber":235,"sourceCode":"\tErrDuplicateServerName = errors.New(\"duplicate server name\")\n\n\t// ErrMinimumVersionRequired is returned when a connection is not at the minimum version required.\n\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","sourceCodeStart":217,"sourceCodeEnd":253,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/errors.go#L217-L253","documentation":"ErrUnknownMappingDestinationFunction is returned when a mapping destination contains a mustache-escaped token ({{...}}) that is not a recognized mapping function (e.g. not split/random or a known function like Wildcard). Both the subject_transform parser (indexPlaceHolders) and sublist destination validation reject such tokens so bad mappings fail at load time rather than at message time.","triggerScenarios":"A mapping destination token like {{Wildcard}} with missing/wrong args, {{splt(1)}} (typo), or any {{foo(...)}} whose name matches neither splitMappingFunctionRegEx nor randomMappingFunctionRegEx nor built-in functions; hit in indexPlaceHolders during transform compilation or in sublist.go:1292 destination validation.","commonSituations":"Typos in function names in server config `mappings`; copying transforms between NATS versions where a function doesn't exist in the older server; missing required arguments so the token fails the function regexes.","solutions":["Correct the function name/args in the destination (e.g. {{SplitFromLeft(1,2)}} or {{Wildcard(1)}}) and verify it against the documented transform functions","Confirm the server version supports the function you used (upgrade if it was added later)","Validate the mapping config with a transform parse before restarting the server"],"exampleFix":"// before\ndest := \"foo.{{splt(1)}}\" // unknown function typo\n// after\ndest := \"foo.{{SplitFromLeft(1)}}\"","handlingStrategy":"validation","validationCode":"for _, tok := range strings.Split(dest, \".\") {\n    if strings.HasPrefix(tok, \"{{\") && !knownTransformFunctionRegEx.MatchString(tok) {\n        return fmt.Errorf(\"unknown transform function in %q\", tok)\n    }\n}","typeGuard":"func destHasKnownFunctions(dest string) bool {\n    _, err := server.NewSubjectTransformWithStrict(\"a.*\", dest)\n    return !errors.Is(err, server.ErrUnknownMappingDestinationFunction)\n}","tryCatchPattern":"if err != nil {\n    if errors.Is(err, server.ErrUnknownMappingDestinationFunction) {\n        return fmt.Errorf(\"typo in transform function: %w\", err)\n    }\n}","preventionTips":["Copy function names only from the documented transform function list","Pin and test mapping configs against the server version in use","Lint mapping entries for {{...}} tokens in CI"],"tags":["subject-mapping","transform","config"],"backgroundTag":"invalid-mapping-destination","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}