{"record":{"id":"72448e6a39052aca","repo":"nats-io/nats-server","slug":"stream-configuration-for-subject-transform-from","errorCode":null,"errorMessage":"stream configuration for subject transform from '%s' to '%s': %w","messagePattern":"stream configuration for subject transform from '(.+?)' to '(.+?)': %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/stream.go","lineNumber":2875,"sourceCode":"\t\t\tcfg.RePublish.Destination = fwcs\n\t\t}\n\t\ttr, err := NewSubjectTransform(cfg.RePublish.Source, cfg.RePublish.Destination)\n\t\tif err != nil {\n\t\t\tmset.mu.Unlock()\n\t\t\treturn fmt.Errorf(\"stream configuration for republish from '%s' to '%s': %w\", cfg.RePublish.Source, cfg.RePublish.Destination, err)\n\t\t}\n\t\t// Assign our transform for republishing.\n\t\tmset.tr = tr\n\t} else {\n\t\tmset.tr = nil\n\t}\n\n\t// Check for changes to subject transform\n\tif ocfg.SubjectTransform == nil && cfg.SubjectTransform != nil {\n\t\ttr, err := NewSubjectTransform(cfg.SubjectTransform.Source, cfg.SubjectTransform.Destination)\n\t\tif err != nil {\n\t\t\tmset.mu.Unlock()\n\t\t\treturn fmt.Errorf(\"stream configuration for subject transform from '%s' to '%s': %w\", cfg.SubjectTransform.Source, cfg.SubjectTransform.Destination, err)\n\t\t}\n\t\tmset.itr = tr\n\t} else if ocfg.SubjectTransform != nil && cfg.SubjectTransform != nil &&\n\t\t(ocfg.SubjectTransform.Source != cfg.SubjectTransform.Source || ocfg.SubjectTransform.Destination != cfg.SubjectTransform.Destination) {\n\t\ttr, err := NewSubjectTransform(cfg.SubjectTransform.Source, cfg.SubjectTransform.Destination)\n\t\tif err != nil {\n\t\t\tmset.mu.Unlock()\n\t\t\treturn fmt.Errorf(\"stream configuration for subject transform from '%s' to '%s': %w\", cfg.SubjectTransform.Source, cfg.SubjectTransform.Destination, err)\n\t\t}\n\t\tmset.itr = tr\n\t} else if ocfg.SubjectTransform != nil && cfg.SubjectTransform == nil {\n\t\tmset.itr = nil\n\t}\n\n\tjs := mset.js\n\n\tif targetTier := tierName(cfg.Replicas); mset.tier != targetTier {\n\t\t// In cases such as R1->R3, only one update is needed","sourceCodeStart":2857,"sourceCodeEnd":2893,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/stream.go#L2857-L2893","documentation":"When a subject transform is being added to a stream for the first time (ocfg.SubjectTransform==nil, cfg.SubjectTransform!=nil), JetStream compiles it with NewSubjectTransform and wraps any failure as \"stream configuration for subject transform from '%s' to '%s'\". The transform cannot be created because the Source/Destination subjects are invalid.","triggerScenarios":"UpdateStream adding StreamConfig.SubjectTransform with a malformed Source or Destination (invalid wildcard usage, mismatched token counts, illegal characters).","commonSituations":"First-time introduction of a transform where Source 'orders.*' is mapped to a Destination with a different wildcard count, or copy-paste of subjects containing trailing dots/spaces.","solutions":["Match wildcard token counts between Source and Destination.","Validate both subjects for syntax before calling UpdateStream.","Inspect the wrapped inner error for the exact rule that failed."],"exampleFix":"// before\nSubjectTransform: &SubjectTransformConfig{Source: \"orders..new\", Destination: \"orders.new\"}\n// after\nSubjectTransform: &SubjectTransformConfig{Source: \"orders.*\", Destination: \"orders.new.*\"}","handlingStrategy":"validation","validationCode":"if st := cfg.SubjectTransform; st != nil {\n    if err := validTransformPair(st.Source, st.Destination); err != nil { return err }\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"subject transform from\") { /* fix SubjectTransform config */ }","preventionTips":["Validate subjects for syntax and matching wildcard counts.","Introduce transforms first on a mirror/test stream."],"tags":["jetstream","subject-transform","validation"],"backgroundTag":"invalid-subject-transform","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}