{"record":{"id":"5daf104a95f7fc9f","repo":"nats-io/nats-server","slug":"invalid-mapping-destination-the-only-mapping-func","errorCode":null,"errorMessage":"invalid mapping destination: the only mapping function allowed for import transforms is {{Wildcard()}}","messagePattern":"invalid mapping destination: the only mapping function allowed for import transforms is (.+?)\\}","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/errors.go","lineNumber":250,"sourceCode":"\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\ntype mappingDestinationErr struct {\n\ttoken string\n\terr   error\n}\n\nfunc (e *mappingDestinationErr) Error() string {\n\tif e.token == _EMPTY_ {\n\t\treturn e.err.Error()\n\t}\n\treturn fmt.Sprintf(\"%s in %s\", e.err, e.token)\n}\n\nfunc (e *mappingDestinationErr) Is(target error) bool {\n\treturn target == ErrInvalidMappingDestination\n}","sourceCodeStart":232,"sourceCodeEnd":268,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/errors.go#L232-L268","documentation":"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.","triggerScenarios":"Creating a stream import (reversible transform) via NewSubjectTransformWithStrict with strict=true and a destination using '{{Split(...)}}' or '{{Join(...)}}' instead of '{{Wildcard()}}'.","commonSituations":"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.","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"],"exampleFix":"// before\ndest := \"in.{{Split(1, 2)}}\" // used in an import transform\n// after\ndest := \"in.{{Wildcard()}}\"","handlingStrategy":"validation","validationCode":"func importDestUsesWildcardOnly(dest string) bool {\n    re := regexp.MustCompile(`\\{\\{(\\w+)`)\n    for _, m := range re.FindAllStringSubmatch(dest, -1) {\n        if m[1] != \"Wildcard\" {\n            return false\n        }\n    }\n    return true\n}","typeGuard":"func isMappingDestinationErr(err error) bool {\n    var mde *mappingDestinationErr\n    return errors.As(err, &mde)\n}","tryCatchPattern":"_, err := NewSubjectTransformWithStrict(dest)\nif errors.Is(err, server.ErrMappingDestinationNotSupportedForImport) {\n    // replace function with {{Wildcard()}} for imports\n}","preventionTips":["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"],"tags":["jetstream","subject-transform","imports"],"backgroundTag":"invalid-subject-mapping-destination","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}