{"record":{"id":"1f48c64a365f3e2e","repo":"micro/go-micro","slug":"error-connecting-to-nats-cluster-v-w","errorCode":null,"errorMessage":"error connecting to nats cluster %v: %w","messagePattern":"error connecting to nats cluster (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"events/natsjs/nats.go","lineNumber":41,"sourceCode":"\n// NewStream returns an initialized nats stream or an error if the connection to the nats\n// server could not be established.\nfunc NewStream(opts ...Option) (events.Stream, error) {\n\t// parse the options\n\toptions := Options{\n\t\tClientID:  uuid.New().String(),\n\t\tClusterID: defaultClusterID,\n\t\tLogger:    logger.DefaultLogger,\n\t}\n\tfor _, o := range opts {\n\t\to(&options)\n\t}\n\n\ts := &stream{opts: options}\n\n\tconn, natsJetStreamCtx, err := connectToNatsJetStream(options)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error connecting to nats cluster %v: %w\", options.ClusterID, err)\n\t}\n\n\ts.conn = conn\n\ts.natsJetStreamCtx = natsJetStreamCtx\n\n\treturn s, nil\n}\n\ntype stream struct {\n\topts             Options\n\tconn             *nats.Conn // store connection for lifecycle management\n\tnatsJetStreamCtx nats.JetStreamContext\n}\n\nfunc connectToNatsJetStream(options Options) (*nats.Conn, nats.JetStreamContext, error) {\n\tnopts := nats.GetDefaultOptions()\n\tif options.TLSConfig != nil {\n\t\tnopts.Secure = true","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/micro/go-micro/blob/24529f140421a11a33b6999ab7944f2021cfd69c/events/natsjs/nats.go#L23-L59","documentation":"NewStream wraps any failure from connectToNatsJetStream (which dials the NATS servers and creates the JetStream context) into 'error connecting to nats cluster <ClusterID>: <cause>'. The wrapped cause carries the real reason — DNS failure, connection refused, TLS error, auth failure, or timeout.","triggerScenarios":"Calling events/natsjs.NewStream when the NATS servers for the configured ClusterID are unreachable: wrong addresses, cluster down, bad credentials/TLS, or the default cluster id 'micro' not matching your deployment.","commonSituations":"Local development without a NATS cluster running; connecting to a NATS cluster whose cluster name differs from the default 'micro'; firewall/network policy blocking port 4222; expired or wrong NATS credentials in the environment.","solutions":["Unwrap the error (%w) and fix the underlying cause — usually connection refused or auth failure at the NATS server","Confirm the NATS servers' addresses via events.Address(...) and that they are reachable (nc -vz host 4222)","Ensure the server's cluster name matches your ClusterID option (default is \"micro\")","Check credentials/TLSConfig options and that JetStream is enabled on the server","Add retry/backoff around NewStream for transient network issues at startup"],"exampleFix":"// before\nstream, err := natsjs.NewStream() // error connecting to nats cluster micro: ...\n// after\nstream, err := natsjs.NewStream(\n    natsjs.Address(\"nats://nats1:4222\", \"nats://nats2:4222\"),\n    natsjs.ClusterID(\"my-cluster\"),\n)","handlingStrategy":"retry","validationCode":"// probe reachability before constructing the stream\nfor _, addr := range addrs {\n    conn, err := net.DialTimeout(\"tcp\", addr, 2*time.Second)\n    if err != nil { return fmt.Errorf(\"nats %s unreachable: %w\", addr, err) }\n    conn.Close()\n}","typeGuard":null,"tryCatchPattern":"var stream events.Stream\nerr := retry.Do(3, 2*time.Second, func() error {\n    s, err := natsjs.NewStream(natsjs.Address(addrs...), natsjs.ClusterID(cluster))\n    if err != nil {\n        log.Warn(\"nats connect failed:\", err) // %w cause is inside\n        return err\n    }\n    stream = s\n    return nil\n})","preventionTips":["Always log the wrapped cause (%w) — it names the real network/auth problem","Match the server's cluster name to your ClusterID option (default \"micro\")","Verify NATS servers are reachable and JetStream is enabled before startup","Use multiple seed addresses and retry with backoff on boot"],"tags":["nats","jetstream","network","connection","events"],"backgroundTag":"nats-connection-failed","analyzedSha":"24529f140421a11a33b6999ab7944f2021cfd69c","analyzedAt":"2026-09-01T02:52:24.923Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}