{"record":{"id":"55c2a45a23d2a12e","repo":"nats-io/nats-server","slug":"invalid-mapping-destination-invalid-transform","errorCode":null,"errorMessage":"invalid mapping destination: invalid transform","messagePattern":"invalid mapping destination: invalid transform","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/errors.go","lineNumber":229,"sourceCode":"\n\t// ErrCertNotPinned is returned when pinned certs are set and the certificate is not in it\n\tErrCertNotPinned = errors.New(\"certificate not pinned\")\n\n\t// ErrDuplicateServerName is returned when processing a server remote connection and\n\t// the server reports that this server name is already used in the cluster.\n\tErrDuplicateServerName = errors.New(\"duplicate server name\")\n\n\t// ErrMinimumVersionRequired is returned when a connection is not at the minimum version required.\n\tErrMinimumVersionRequired = errors.New(\"minimum version required\")\n\t// ErrLeafNodeMinVersionRejected is the leafnode protocol error prefix used\n\t// when rejecting a remote due to leafnodes.min_version.\n\tErrLeafNodeMinVersionRejected = errors.New(\"connection rejected since minimum version required is\")\n\n\t// ErrInvalidMappingDestination is used for all subject mapping destination errors\n\tErrInvalidMappingDestination = errors.New(\"invalid mapping destination\")\n\n\t// ErrInvalidMappingDestinationSubject is used to error on a bad transform destination mapping\n\tErrInvalidMappingDestinationSubject = fmt.Errorf(\"%w: invalid transform\", ErrInvalidMappingDestination)\n\n\t// ErrMappingDestinationNotUsingAllWildcards is used to error on a transform destination not using all of the token wildcards\n\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)","sourceCodeStart":211,"sourceCodeEnd":247,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/errors.go#L211-L247","documentation":"ErrInvalidMappingDestinationSubject wraps ErrInvalidMappingDestination and signals that a subject mapping/transform destination is structurally invalid — it does not parse as a legal destination subject. The server returns this when validating a destination (e.g. in TestValidateDestinationSubject or when building a mapping destination in sublist.go) and the destination token list is empty or uses patterns the destination grammar forbids (such as a lone wildcard where none is allowed).","triggerScenarios":"Creating a subject transform/mapping whose destination subject is empty, or ends in/consists of tokens the destination grammar rejects (e.g. wildcard-only destination like '>' or '*' where a concrete token is required); AddStream sourcing/mirroring with an invalid External target subject; SetMapping with a bad destination.","commonSituations":"Typo'd or truncated mapping destinations in nats-server config (`mappings` block); JetStream source/transform configs with a destination subject missing required tokens; programmatic subject transform construction with empty strings.","solutions":["Fix the mapping destination so it is a well-formed subject with the required concrete tokens (use all source wildcards if the source has them)","Validate the destination with a transform parser before applying config","Check errors.Is(err, ErrInvalidMappingDestination) to confirm the family, then read the wrapped cause"],"exampleFix":"// before\ntransformDest := \"foo.>\" // invalid: bare wildcard not allowed as full destination here\n// after\ntransformDest := \"foo.{{Wildcard(1)}}\" // reuse the source wildcard via a transform function","handlingStrategy":"validation","validationCode":"_, err := server.NewSubjectTransformWithStrict(src, dest)\nif err != nil {\n    return fmt.Errorf(\"bad mapping dest %q: %w\", dest, err)\n}","typeGuard":"func isValidMappingDest(src, dest string) bool {\n    _, err := server.NewSubjectTransformWithStrict(src, dest)\n    return err == nil\n}","tryCatchPattern":"if err != nil {\n    if errors.Is(err, server.ErrInvalidMappingDestination) {\n        log.Fatalf(\"invalid mapping destination in config: %v\", err)\n    }\n}","preventionTips":["Validate mapping configs at startup with a transform parse","Never leave destination subjects empty or wildcard-only","Cover every mappings entry in config tests"],"tags":["subject-mapping","transform","config"],"backgroundTag":"invalid-mapping-destination","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}