{"record":{"id":"5ebfd569fb7eb011","repo":"nats-io/nats-server","slug":"failed-to-create-mapping-transform-for-stream-impo","errorCode":null,"errorMessage":"failed to create mapping transform for stream import subject from %q to %q: %v","messagePattern":"failed to create mapping transform for stream import subject from %q to %q: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/accounts.go","lineNumber":2774,"sourceCode":"\t\treturn err\n\t}\n\n\tif err := a.streamImportFormsCycle(account, from); err != nil {\n\t\treturn err\n\t}\n\n\tvar (\n\t\tusePub bool\n\t\ttr     *subjectTransform\n\t\terr    error\n\t)\n\tif subjectHasWildcard(from) {\n\t\tif to == from {\n\t\t\tusePub = true\n\t\t} else {\n\t\t\t// Create a transform\n\t\t\tif tr, err = NewSubjectTransformStrict(from, transformTokenize(to)); err != nil {\n\t\t\t\treturn fmt.Errorf(\"failed to create mapping transform for stream import subject from %q to %q: %v\",\n\t\t\t\t\tfrom, to, err)\n\t\t\t}\n\t\t\tto, _ = transformUntokenize(to)\n\t\t}\n\t}\n\n\ta.mu.Lock()\n\tif a.isStreamImportDuplicate(account, from) {\n\t\ta.mu.Unlock()\n\t\treturn ErrStreamImportDuplicate\n\t}\n\tif imClaim != nil {\n\t\tallowTrace = imClaim.AllowTrace\n\t}\n\ta.imports.streams = append(a.imports.streams, &streamImport{account, from, to, tr, nil, imClaim, usePub, false, allowTrace})\n\ta.mu.Unlock()\n\treturn nil\n}","sourceCodeStart":2756,"sourceCodeEnd":2792,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/accounts.go#L2756-L2792","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","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"],"exampleFix":"// before\n{\"imports\":[{\"stream\":{\"from\":\"prod.*.telemetry\",\"to\":\"telemetry\"}}]}\n// after\n{\"imports\":[{\"stream\":{\"from\":\"prod.*.telemetry\",\"to\":\"telemetry.$1\"}}]}","handlingStrategy":"validation","validationCode":"if subjectHasWildcard(from) && to != from {\n    if _, err := NewSubjectTransformStrict(from, transformTokenize(to)); err != nil {\n        return fmt.Errorf(\"invalid stream import mapping %q -> %q: %v\", from, to, err)\n    }\n}\n","typeGuard":null,"tryCatchPattern":"if err := acc.UpdateImports(imports); err != nil {\n    if strings.Contains(err.Error(), \"failed to create mapping transform\") {\n        // fix from/to token structure and retry\n    }\n}\n","preventionTips":["Keep 'to' token-compatible with wildcard 'from' (same token count, valid placeholders)","Set 'to' == 'from' for passthrough imports","Validate transforms before pushing account claims"],"tags":["nats-server","stream-imports","subject-transform","configuration"],"backgroundTag":"invalid-subject-transform","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}