nats-io/nats-server · error

invalid mapping destination: invalid transform

Error message

invalid mapping destination: invalid transform

What it means

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

Source

Thrown at server/errors.go:229

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

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

View on GitHub (pinned to 3a66a489d2)

Solutions

1. 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)
2. Validate the destination with a transform parser before applying config
3. Check errors.Is(err, ErrInvalidMappingDestination) to confirm the family, then read the wrapped cause

Example fix

// before
transformDest := "foo.>" // invalid: bare wildcard not allowed as full destination here
// after
transformDest := "foo.{{Wildcard(1)}}" // reuse the source wildcard via a transform function

_, err := server.NewSubjectTransformWithStrict(src, dest)
if err != nil {
    return fmt.Errorf("bad mapping dest %q: %w", dest, err)
}

func isValidMappingDest(src, dest string) bool {
    _, err := server.NewSubjectTransformWithStrict(src, dest)
    return err == nil
}

if err != nil {
    if errors.Is(err, server.ErrInvalidMappingDestination) {
        log.Fatalf("invalid mapping destination in config: %v", err)
    }
}

When it happens

Trigger: 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.

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

Related errors

• invalid mapping destination: unknown function
• invalid mapping destination: not using all of the token wild
• invalid mapping destination
• mqtt authentication token not compatible with presence of us
• ack wait must be a positive value

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