nats-io/nats-server · error

invalid mapping destination: function argument is invalid or

Error message

invalid mapping destination: function argument is invalid or in the wrong format

What it means

This error wraps ErrInvalidMappingDestination and is thrown when an argument to a mapping destination function cannot be parsed as the expected integer type. transformIndexIntArgsHelper uses strconv.Atoi on args[0] (wildcard index) and strconv.ParseInt on args[1] (32-bit int value); a non-numeric argument fails parsing and produces this error.

Source

Thrown at server/errors.go:244

	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
}

func (e *mappingDestinationErr) Error() string {
	if e.token == _EMPTY_ {
		return e.err.Error()
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Ensure args[0] is a plain decimal integer (the wildcard index) and args[1] is a decimal integer that fits in 32 bits
2. Remove stray quotes, units, or letters from the function arguments
3. Check the generated account config JSON/YAML for escaping issues around the destination string

Example fix

// before
dest := "out.{{Split(one, 2)}}"
// after
dest := "out.{{Split(1, 2)}}"

func argsAreInts(dest string) bool {
    re := regexp.MustCompile(`\{\{(?:Split|Join)\(([^,]*),([^)]*)\)\}}`)
    for _, m := range re.FindAllStringSubmatch(dest, -1) {
        if _, err := strconv.Atoi(strings.TrimSpace(m[1])); err != nil {
            return false
        }
        if _, err := strconv.ParseInt(strings.TrimSpace(m[2]), 10, 32); err != nil {
            return false
        }
    }
    return true
}

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

_, err := NewSubjectTransformWithStrict(dest)
if errors.Is(err, server.ErrMappingDestinationInvalidArg) {
    // args must be decimal integers
}

When it happens

Trigger: Calling NewSubjectTransformWithStrict with a destination function whose arguments are non-numeric or malformed, e.g. '{{Split(a, b)}}' or arguments containing characters that fail strconv parsing after space trimming.

Common situations: Typos like '{{Split(*, o)}}' (letter o instead of zero) in account mapping config; quoting or whitespace artifacts introduced by YAML/JSON config generation tools.

Related errors

• invalid mapping destination: wildcard index out of range
• invalid mapping destination: not enough arguments passed to
• invalid mapping destination: too many arguments passed to th
• max_request_batch must be set if it's JetStream limits are s
• consumer name can not contain '.', '*', '>', '\', '/'

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