failed to create mapping transform for service import subjec

Error message

failed to create mapping transform for service import subject from %q to %q: %v

What it means

AddServiceImport failed to build the subject transform mapping the exported subject back to the local one (server/accounts.go:2190). The server creates a strict reverse transform between 'to' and 'from'; invalid or incompatible token patterns in either subject make NewSubjectTransformStrict fail.

Source

Thrown at server/accounts.go:2190

		to = from
	}
	// Check to see if we have a wildcard
	var (
		usePub bool
		tr     *subjectTransform
		err    error
	)

	if subjectHasWildcard(to) {
		// If to and from match, then we use the published subject.
		if to == from {
			usePub = true
		} else {
			to, _ = transformUntokenize(to)
			// Create a transform. Do so in reverse such that $ symbols only exist in to
			if tr, err = NewSubjectTransformStrict(to, transformTokenize(from)); err != nil {
				a.mu.Unlock()
				return nil, fmt.Errorf("failed to create mapping transform for service import subject from %q to %q: %v",
					from, to, err)
			} else {
				// un-tokenize and reverse transform so we get the transform needed
				from, _ = transformUntokenize(from)
				tr = tr.reverse()
			}
		}
	}
	var share bool
	if claim != nil {
		share = claim.Share
	}
	si := &serviceImport{dest, claim, se, nil, from, to, tr, 0, rt, lat, nil, nil, nil, usePub, false, false, share, false, false, atrc, nil}
	sis := a.imports.services[from]
	sis = append(sis, si)
	a.imports.services[from] = sis
	a.mu.Unlock()

View on GitHub (pinned to 3a66a489d2)

Solutions

Ensure 'to' and 'from' have compatible token counts and wildcard placement.
If using $ tokens in 'to', mirror the same tokenization in 'from'.
Simplify subjects to plain literals/wildcards if transforms are not needed.
Inspect the wrapped inner error (%v) for the exact transform failure reason.

Example fix

// before
acc.AddServiceImport(dest, "req.*", "help.a.b.c") // incompatible token counts
// after
acc.AddServiceImport(dest, "req.*", "help.*")

Defensive patterns

Strategy: validation

Validate before calling

if _, err := NewSubjectTransformStrict(to, from); err != nil {
    return fmt.Errorf("invalid from/to pair: %v", err)
}

Try / catch

if _, err := acc.AddServiceImport(dest, from, to); err != nil {
    if strings.Contains(err.Error(), "failed to create mapping transform") {
        // fix token structure of from/to
    }
}

Prevention

Keep token counts equal between from and to
Mirror $ placeholders on both sides
Prefer simple subjects when transforms are unnecessary

When it happens

Trigger: Calling AddServiceImport with 'from'/'to' subjects whose wildcard/token structure cannot be transformed (e.g. mismatched wildcard counts, illegal $ placeholders, invalid tokens after untokenizing).

Common situations: Using $-token placeholders inconsistently between from and to; wildcards in 'to' not present in 'from'; subjects with invalid characters.

Related errors

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