{"record":{"id":"88f8189d86c92e5f","repo":"benbjohnson/litestream","slug":"nats-failed-to-connect-w","errorCode":null,"errorMessage":"nats: failed to connect: %w","messagePattern":"nats: failed to connect: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nats/replica_client.go","lineNumber":139,"sourceCode":"}\n\n// Type returns \"nats\" as the client type.\nfunc (c *ReplicaClient) Type() string {\n\treturn ReplicaClientType\n}\n\n// Init initializes the connection to NATS JetStream. No-op if already initialized.\nfunc (c *ReplicaClient) Init(ctx context.Context) error {\n\tc.mu.Lock()\n\tdefer c.mu.Unlock()\n\n\tif c.objectStore != nil {\n\t\treturn nil\n\t}\n\n\tif c.nc == nil {\n\t\tif err := c.connect(ctx); err != nil {\n\t\t\treturn fmt.Errorf(\"nats: failed to connect: %w\", err)\n\t\t}\n\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()...)","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/nats/replica_client.go#L121-L157","documentation":"ReplicaClient.Init ensures the NATS connection exists, wrapping any failure from the internal connect() step with this prefix. Init is called before every replica operation, so this error means litestream could not establish (or reuse) a connection to the NATS server and cannot reach the replica.","triggerScenarios":"Any ReplicaClient.Init call where c.nc == nil and connect() fails: NATS server unreachable, wrong host/port in the URL, TLS or auth rejections, or the server not accepting connections.","commonSituations":"NATS server down or restarted; wrong URL/port in litestream config; credentials required but not supplied; firewall blocking port 4222; NATS running in a different container/network namespace.","solutions":["Verify the NATS server is running and reachable: `nats server report` or `nats -s nats://host:4222 server info`","Fix host/port/credentials in the litestream replica URL config","Inspect the inner wrapped error for the specific cause (timeout, auth, TLS)","Check network/firewall/DNS between litestream and the NATS server"],"exampleFix":"// before\nurl: \"nats://nats.internal:4222/backups\"\n// after (with credentials the server requires)\nurl: \"nats://user:pass@nats.internal:4222/backups\"","handlingStrategy":"try-catch","validationCode":"// before Init, verify the server accepts connections\nconn, err := net.DialTimeout(\"tcp\", \"nats.example.com:4222\", 3*time.Second)\nif err != nil {\n\treturn fmt.Errorf(\"NATS server unreachable: %w\", err)\n}\nconn.Close()","typeGuard":null,"tryCatchPattern":"if err := client.Init(ctx); err != nil {\n\tvar netErr net.Error\n\tif errors.As(err, &netErr) {\n\t\treturn fmt.Errorf(\"transient NATS outage, will retry: %w\", err)\n\t}\n\treturn err\n}","preventionTips":["Health-check the NATS server before starting litestream","Supply credentials/TLS options in the replica URL when the server requires them","Monitor NATS server uptime and alerts","Use the client port (4222), not the monitoring port (8222)"],"tags":["nats","network","connection","replication"],"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"}