nats-io/nats-server · error

invalid mapping destination

Error message

invalid mapping destination

What it means

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.

Source

Thrown at server/errors.go:226

	// ErrNoTransforms signals no subject transforms are available to map this subject.
	ErrNoTransforms = errors.New("no matching transforms available")

	// ErrCertNotPinned is returned when pinned certs are set and the certificate is not in it
	ErrCertNotPinned = errors.New("certificate not pinned")

	// ErrDuplicateServerName is returned when processing a server remote connection and
	// the server reports that this server name is already used in the cluster.
	ErrDuplicateServerName = errors.New("duplicate server name")

	// ErrMinimumVersionRequired is returned when a connection is not at the minimum version required.
	ErrMinimumVersionRequired = errors.New("minimum version required")
	// ErrLeafNodeMinVersionRejected is the leafnode protocol error prefix used
	// when rejecting a remote due to leafnodes.min_version.
	ErrLeafNodeMinVersionRejected = errors.New("connection rejected since minimum version required is")

	// ErrInvalidMappingDestination is used for all subject mapping destination errors
	ErrInvalidMappingDestination = errors.New("invalid mapping destination")

	// ErrInvalidMappingDestinationSubject is used to error on a bad transform destination mapping
	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)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Validate the destination subject in your mappings config: it must be a valid NATS subject and use wildcard tokens correctly.
2. If using a transform destination, ensure it satisfies 'not using all of the token wildcard(s)' rules - every source wildcard must be consumed properly.
3. Run the config through nats-server --test (config validation) before restarting to catch mapping errors early.

Example fix

// before
mappings: {
  "foo.*.bar": "bar baz"  // destination missing wildcard usage
}
// after
mappings: {
  "foo.*.bar": "bar.$1"  // hmm: correct form is {{ wildcard token usage }}
}

if !IsValidMappingDestination(dest) {
    return fmt.Errorf("invalid mapping destination %q", dest)
}

if errors.Is(err, server.ErrInvalidMappingDestination) {
    return fmt.Errorf("fix mappings config: %w", err)
}

When it happens

Trigger: 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", ...)).

Common situations: 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.

Related errors

• account jwt not found
• subject has exceeded number of tokens limit
• attempted to connect to route port
• attempted to connect to leaf node port
• remote leafnode has same cluster name

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