invalid mapping destination: too many arguments passed to th

Error message

invalid mapping destination: too many arguments passed to the function

What it means

This error wraps ErrInvalidMappingDestination and is thrown when a mapping destination function is passed more arguments than allowed. transformIndexIntArgsHelper rejects more than 2 args, and a Wildcard destination token with any argument beyond the single allowed form is rejected in indexPlaceHolders.

Source

Thrown at server/errors.go:247

	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()
	}
	return fmt.Sprintf("%s in %s", e.err, e.token)
}

View on GitHub (pinned to 3a66a489d2)

Solutions

Reduce the function to at most 2 arguments, e.g. '{{Split(index, value)}}'
Use '{{Wildcard()}}' with no extra arguments for plain wildcard mapping destinations
Validate the transform with NewSubjectTransformWithStrict before applying it

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

func argCountOK(dest string) bool {
    re := regexp.MustCompile(`\{\{\w+\((.*)\)\}}`)
    for _, m := range re.FindAllStringSubmatch(dest, -1) {
        inner := strings.TrimSpace(m[1])
        if inner == "" {
            continue
        }
        if n := len(strings.Split(inner, ",")); n > 2 {
            return false
        }
    }
    return true
}

Type guard

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

Try / catch

_, err := NewSubjectTransformWithStrict(dest)
if errors.Is(err, server.ErrMappingDestinationTooManyArgs) {
    // trim function to at most 2 args
}

Prevention

Limit destination functions to at most 2 arguments
Never add extra parameters to {{Wildcard()}}
Test every mapping string with NewSubjectTransformWithStrict before deployment

When it happens

Trigger: Calling NewSubjectTransformWithStrict with '{{Split(1, 2, 3)}}' (3 args) or a wildcard destination token carrying extra parenthesized arguments.

Common situations: Misunderstanding of the mapping function grammar when writing stream import mappings; accidentally leaving placeholder arguments from a copied example.

Related errors

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