{"record":{"id":"b3a66480910d2a7a","repo":"nats-io/nats-server","slug":"invalid-mapping-destination","errorCode":null,"errorMessage":"invalid mapping destination","messagePattern":"invalid mapping destination","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/errors.go","lineNumber":226,"sourceCode":"\n\t// ErrNoTransforms signals no subject transforms are available to map this subject.\n\tErrNoTransforms = errors.New(\"no matching transforms available\")\n\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)","sourceCodeStart":208,"sourceCodeEnd":244,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/errors.go#L208-L244","documentation":"ErrInvalidMappingDestination is used for all subject mapping destination errors in nats-server. Derived errors such as ErrInvalidMappingDestinationSubject ('invalid transform') and ErrMappingDestinationNotUsingAllWildcards wrap it, so errors.Is(err, ErrInvalidMappingDestination) matches the whole family of bad mapping-destination configurations.","triggerScenarios":"A subject mapping orx-transform destination is invalid, e.g. mappings configured in accounts/config with a destination subject that is not a valid subject, contains an invalid transform, or fails wildcard token requirements (server/errors.go:229 wraps it via fmt.Errorf(\"%w: invalid transform\", ...)).","commonSituations":"Typos in mapping destination subjects, using $ tokens/wildcards incorrectly in destination mappings, bad Transform definitions in account or server mappings config, operator/jwt account mappings with malformed destinations.","solutions":["Validate the destination subject in your mappings config: it must be a valid NATS subject and use wildcard tokens correctly.","If using a transform destination, ensure it satisfies 'not using all of the token wildcard(s)' rules - every source wildcard must be consumed properly.","Run the config through nats-server --test (config validation) before restarting to catch mapping errors early."],"exampleFix":"// before\nmappings: {\n  \"foo.*.bar\": \"bar baz\"  // destination missing wildcard usage\n}\n// after\nmappings: {\n  \"foo.*.bar\": \"bar.$1\"  // hmm: correct form is {{ wildcard token usage }}\n}","handlingStrategy":"validation","validationCode":"if !IsValidMappingDestination(dest) {\n    return fmt.Errorf(\"invalid mapping destination %q\", dest)\n}","typeGuard":null,"tryCatchPattern":"if errors.Is(err, server.ErrInvalidMappingDestination) {\n    return fmt.Errorf(\"fix mappings config: %w\", err)\n}","preventionTips":["Run nats-server config validation (--test) in CI to catch mapping errors before deploy.","Keep transforms simple and verify wildcard token usage in destinations.","Use nsc/config review when changing account mappings."],"tags":["nats","subject-mapping","configuration","transforms"],"backgroundTag":"invalid-mapping-destination","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}