failed to create mapping transform for stream import subject

Error message

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

What it means

When a stream import uses a wildcard 'from' subject that differs from 'to', the server builds a strict subject mapping transform via NewSubjectTransformStrict(from, transformTokenize(to)). If that transform cannot be constructed (incompatible token counts/shapes between from and to), the import setup fails with this wrapped error.

Source

Thrown at server/accounts.go:2774

		return err
	}

	if err := a.streamImportFormsCycle(account, from); err != nil {
		return err
	}

	var (
		usePub bool
		tr     *subjectTransform
		err    error
	)
	if subjectHasWildcard(from) {
		if to == from {
			usePub = true
		} else {
			// Create a transform
			if tr, err = NewSubjectTransformStrict(from, transformTokenize(to)); err != nil {
				return fmt.Errorf("failed to create mapping transform for stream import subject from %q to %q: %v",
					from, to, err)
			}
			to, _ = transformUntokenize(to)
		}
	}

	a.mu.Lock()
	if a.isStreamImportDuplicate(account, from) {
		a.mu.Unlock()
		return ErrStreamImportDuplicate
	}
	if imClaim != nil {
		allowTrace = imClaim.AllowTrace
	}
	a.imports.streams = append(a.imports.streams, &streamImport{account, from, to, tr, nil, imClaim, usePub, false, allowTrace})
	a.mu.Unlock()
	return nil
}

View on GitHub (pinned to 3a66a489d2)

Solutions

Make 'to' a token-compatible mapping of 'from' (same token count, valid wildcard placeholders)
If a 1:1 passthrough is intended, set 'to' equal to 'from' so usePub path is taken instead
Validate the transform locally with NewSubjectTransformStrict before pushing the account claim
Check the inner error (%v) for the exact token mismatch

Example fix

// before
{"imports":[{"stream":{"from":"prod.*.telemetry","to":"telemetry"}}]}
// after
{"imports":[{"stream":{"from":"prod.*.telemetry","to":"telemetry.$1"}}]}

Defensive patterns

Strategy: validation

Validate before calling

if subjectHasWildcard(from) && to != from {
    if _, err := NewSubjectTransformStrict(from, transformTokenize(to)); err != nil {
        return fmt.Errorf("invalid stream import mapping %q -> %q: %v", from, to, err)
    }
}

Try / catch

if err := acc.UpdateImports(imports); err != nil {
    if strings.Contains(err.Error(), "failed to create mapping transform") {
        // fix from/to token structure and retry
    }
}

Prevention

Keep 'to' token-compatible with wildcard 'from' (same token count, valid placeholders)
Set 'to' == 'from' for passthrough imports
Validate transforms before pushing account claims

When it happens

Trigger: Adding a stream import (account claims / UpdateImports) where 'from' has wildcards, 'to' != 'from', and the 'to' subject cannot be token-mapped onto 'from' — e.g. mismatched number of wildcard tokens or invalid placeholder references in 'to'.

Common situations: Miswritten account claim imports like from: 'prod.*.telemetry' mapped to a 'to' with a different token structure; typos in $-placeholders; version differences where strict transform validation rejects previously-tolerated mappings.

Related errors

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