invalid mapping destination: the only mapping function allow

Error message

invalid mapping destination: the only mapping function allowed for import transforms is {{Wildcard()}}

What it means

This error wraps ErrInvalidMappingDestination and is returned by NewSubjectTransformWithStrict (strict mode) when a destination transform uses a mapping function other than Wildcard. Import transforms must be reversible, and only wildcard mapping preserves reversibility, so functions like Split or Join are disallowed there.

Source

Thrown at server/errors.go:250

	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)
}

func (e *mappingDestinationErr) Is(target error) bool {
	return target == ErrInvalidMappingDestination
}

View on GitHub (pinned to 3a66a489d2)

Solutions

Replace the destination function with '{{Wildcard()}}' for import transforms
Move the complex mapping to the export side, where non-wildcard functions are permitted
Use strict=false only if you truly do not need a reversible transform

Example fix

// before
dest := "in.{{Split(1, 2)}}" // used in an import transform
// after
dest := "in.{{Wildcard()}}"

Defensive patterns

Strategy: validation

Validate before calling

func importDestUsesWildcardOnly(dest string) bool {
    re := regexp.MustCompile(`\{\{(\w+)`)
    for _, m := range re.FindAllStringSubmatch(dest, -1) {
        if m[1] != "Wildcard" {
            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.ErrMappingDestinationNotSupportedForImport) {
    // replace function with {{Wildcard()}} for imports
}

Prevention

Use only {{Wildcard()}} in import (reversible) transforms
Put complex Split/Join mappings on the export side instead
Do not pass strict=false just to bypass the check; it breaks reversibility

When it happens

Trigger: Creating a stream import (reversible transform) via NewSubjectTransformWithStrict with strict=true and a destination using '{{Split(...)}}' or '{{Join(...)}}' instead of '{{Wildcard()}}'.

Common situations: Configuring mirrored/imported subjects with a complex mapping copied from an export transform; using non-wildcard functions where the client expects the original subject to be recoverable.

Related errors

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