{"record":{"id":"3309c9e1659d5054","repo":"benbjohnson/litestream","slug":"failed-to-connect-to-nats-server-w","errorCode":null,"errorMessage":"failed to connect to NATS server: %w","messagePattern":"failed to connect to NATS server: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nats/replica_client.go","lineNumber":159,"sourceCode":"\t}\n\n\tif err := c.initObjectStore(ctx); err != nil {\n\t\treturn fmt.Errorf(\"nats: failed to initialize object store: %w\", err)\n\t}\n\n\treturn nil\n}\n\n// connect establishes a connection to NATS server with proper configuration.\nfunc (c *ReplicaClient) connect(_ context.Context) error {\n\turl := c.URL\n\tif url == \"\" {\n\t\turl = nats.DefaultURL\n\t}\n\n\tnc, err := nats.Connect(url, c.options()...)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to connect to NATS server: %w\", err)\n\t}\n\n\tjs, err := jetstream.New(nc)\n\tif err != nil {\n\t\tnc.Close()\n\t\treturn fmt.Errorf(\"failed to create JetStream context: %w\", err)\n\t}\n\n\tc.nc = nc\n\tc.js = js\n\treturn nil\n}\n\nfunc (c *ReplicaClient) options() []nats.Option {\n\topts := []nats.Option{\n\t\tnats.MaxReconnects(c.MaxReconnects),\n\t\tnats.ReconnectWait(c.ReconnectWait),\n\t\tnats.ReconnectJitter(c.ReconnectJitter, c.ReconnectJitter*2),","sourceCodeStart":141,"sourceCodeEnd":177,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/nats/replica_client.go#L141-L177","documentation":"The internal connect() method calls nats.Connect with the configured URL and client options; this error wraps any connection failure. Unlike error 362, this is the innermost cause — it surfaces the NATS client library's own reason (refused, timeout, auth, TLS).","triggerScenarios":"nats.Connect(url, c.options()...) returns an error during connect() (reached via Init): no listener at the URL, connection timeout, auth violation, or TLS handshake failure.","commonSituations":"NATS not running on the configured host/port; wrong port (4222 vs 8222 monitoring port); credentials missing/rotated; TLS required by server but client options lack certs; DNS failure in containers.","solutions":["Test connectivity first: `nc -zv host 4222` or `nats -s <url> server info`","Confirm the URL scheme/port (nats:// vs tls://, default port 4222)","Supply required credentials in the URL or client options","Inspect the inner %w error for auth/TLS specifics and fix accordingly"],"exampleFix":"# before (monitoring port instead of client port)\nurl: \"nats://host:8222/backups\"\n# after\nurl: \"nats://host:4222/backups\"","handlingStrategy":"try-catch","validationCode":"u, _ := url.Parse(strings.TrimPrefix(replicaURL, \"nats://\"))\nhp := net.JoinHostPort(u.Hostname(), u.Port() or \"4222\")\nif c, err := net.DialTimeout(\"tcp\", hp, 3*time.Second); err != nil {\n\treturn fmt.Errorf(\"cannot reach NATS at %s: %w\", hp, err)\n} else { c.Close() }","typeGuard":null,"tryCatchPattern":"if err := client.Init(ctx); err != nil {\n\tif strings.Contains(err.Error(), \"failed to connect to NATS server\") {\n\t\t// inspect wrapped cause: timeouts, auth violations, TLS errors\n\t\treturn retry.WithBackoff(ctx, client.Init) // transient outages\n\t}\n\treturn err\n}","preventionTips":["Confirm host/port/credentials with `nats -s <url> server info` before rollout","Use nats:// vs tls:// scheme matching the server's TLS config","Monitor NATS connectivity from the litestream host"],"tags":["nats","network","connection","tcp"],"backgroundTag":"connection-refused","analyzedSha":"4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3","analyzedAt":"2026-09-06T18:29:25.564Z","contentChangedAt":"2026-09-06T18:29:25.564Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}