nats-io/nats-server · error

invalid mapping destination: unknown function

Error message

invalid mapping destination: unknown function

What it means

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.

Source

Thrown at server/errors.go:235

	ErrDuplicateServerName = errors.New("duplicate server name")

	// ErrMinimumVersionRequired is returned when a connection is not at the minimum version required.
	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

View on GitHub (pinned to 3a66a489d2)

Solutions

  1. Correct the function name/args in the destination (e.g. {{SplitFromLeft(1,2)}} or {{Wildcard(1)}}) and verify it against the documented transform functions
  2. Confirm the server version supports the function you used (upgrade if it was added later)
  3. Validate the mapping config with a transform parse before restarting the server

Example fix

// before
dest := "foo.{{splt(1)}}" // unknown function typo
// after
dest := "foo.{{SplitFromLeft(1)}}"
Defensive patterns

Strategy: validation

Validate before calling

for _, tok := range strings.Split(dest, ".") {
    if strings.HasPrefix(tok, "{{") && !knownTransformFunctionRegEx.MatchString(tok) {
        return fmt.Errorf("unknown transform function in %q", tok)
    }
}

Type guard

func destHasKnownFunctions(dest string) bool {
    _, err := server.NewSubjectTransformWithStrict("a.*", dest)
    return !errors.Is(err, server.ErrUnknownMappingDestinationFunction)
}

Try / catch

if err != nil {
    if errors.Is(err, server.ErrUnknownMappingDestinationFunction) {
        return fmt.Errorf("typo in transform function: %w", err)
    }
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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