{"record":{"id":"0dba1f6601062edf","repo":"apache/beam","slug":"error-connecting-to-nats-v","errorCode":null,"errorMessage":"error connecting to NATS: %v","messagePattern":"error connecting to NATS: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"sdks/go/pkg/beam/io/natsio/common.go","lineNumber":45,"sourceCode":"\tURI       string\n\tCredsFile string\n\tnc        *nats.Conn\n\tjs        jetstream.JetStream\n}\n\nfunc (fn *natsFn) Setup() error {\n\tif fn.nc != nil && fn.js != nil {\n\t\treturn nil\n\t}\n\n\tvar opts []nats.Option\n\tif fn.CredsFile != \"\" {\n\t\topts = append(opts, nats.UserCredentials(fn.CredsFile))\n\t}\n\n\tconn, err := nats.Connect(fn.URI, opts...)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error connecting to NATS: %v\", err)\n\t}\n\tfn.nc = conn\n\n\tjs, err := jetstream.New(fn.nc)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error creating JetStream context: %v\", err)\n\t}\n\tfn.js = js\n\n\treturn nil\n}\n\nfunc (fn *natsFn) Teardown() {\n\tif fn.nc != nil {\n\t\tfn.nc.Close()\n\t}\n}\n","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/go/pkg/beam/io/natsio/common.go#L27-L63","documentation":"Setup for the NATS IO functions calls nats.Connect(fn.URI, opts...) to establish the client connection (optionally with credentials from fn.CredsFile). If the connection cannot be established, the error is wrapped with this message and Setup fails, aborting the DoFn lifecycle. It means the worker could not reach or authenticate to the NATS server.","triggerScenarios":"nats.Connect returns an error: server unreachable at fn.URI, invalid credentials file, TLS handshake failure, auth mismatch, or connection timeout.","commonSituations":"Typo in NATS URI or wrong port; NATS server down or behind a firewall; stale or malformed .creds file passed via CredsFile; NATS cluster requiring auth but no credentials configured; DNS resolution failure in the Beam worker environment.","solutions":["Verify fn.URI is reachable from the worker (nc URI should look like nats://host:4222) and the server is up","Check network/firewall rules and DNS from the Beam worker environment","Validate fn.CredsFile exists and holds valid NATS credentials; remove it if the server requires none","Increase nats.Connect timeouts/retries options if the server is slow to accept connections","Test connectivity independently (e.g. `nats --server <uri> status`) before running the pipeline"],"exampleFix":"// before\nURI: \"nats://nats.prod:4222\" // host not resolvable from workers\n// after\nURI: \"nats://nats.prod.internal:4222\" // verified reachable; plus:\nopts = append(opts, nats.RetryOnFailedConnect(true), nats.ConnectTimeout(10*time.Second))","handlingStrategy":"validation","validationCode":"// pre-flight check before starting the pipeline\nconn, err := nats.Connect(uri, nats.Timeout(5*time.Second), nats.UserCredentials(credsFile))\nif err != nil {\n\treturn fmt.Errorf(\"NATS preflight connect failed for %s: %w\", uri, err)\n}\nconn.Close()","typeGuard":"func validNATSURI(uri string) bool {\n\tu, err := url.Parse(uri)\n\treturn err == nil && (u.Scheme == \"nats\" || u.Scheme == \"tls\" || u.Scheme == \"nats\") && u.Host != \"\"\n}","tryCatchPattern":"if err := fn.Setup(ctx); err != nil {\n\tvar connErr *nats.Error\n\tif errors.As(err, &connErr) && connErr.Timeout() {\n\t\t// retry Setup with backoff\n\t}\n\treturn fmt.Errorf(\"setup failed: %w\", err)\n}","preventionTips":["Resolve the NATS URI from a verified config; never hardcode environment-specific hosts","Run a connectivity preflight from the same network the workers use","Keep CredsFile packaged/accessible to workers and rotate credentials before expiry","Set explicit ConnectTimeout and RetryOnFailedConnect options","Monitor NATS server availability and alert before job launches"],"tags":["nats","connection","network","beam-io"],"backgroundTag":"connection-refused","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}