benbjohnson/litestream · error

nats: failed to connect: %w

Error message

nats: failed to connect: %w

What it means

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.

Source

Thrown at nats/replica_client.go:139

}

// Type returns "nats" as the client type.
func (c *ReplicaClient) Type() string {
	return ReplicaClientType
}

// Init initializes the connection to NATS JetStream. No-op if already initialized.
func (c *ReplicaClient) Init(ctx context.Context) error {
	c.mu.Lock()
	defer c.mu.Unlock()

	if c.objectStore != nil {
		return nil
	}

	if c.nc == nil {
		if err := c.connect(ctx); err != nil {
			return fmt.Errorf("nats: failed to connect: %w", err)
		}
	}

	if err := c.initObjectStore(ctx); err != nil {
		return fmt.Errorf("nats: failed to initialize object store: %w", err)
	}

	return nil
}

// connect establishes a connection to NATS server with proper configuration.
func (c *ReplicaClient) connect(_ context.Context) error {
	url := c.URL
	if url == "" {
		url = nats.DefaultURL
	}

	nc, err := nats.Connect(url, c.options()...)

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Verify the NATS server is running and reachable: `nats server report` or `nats -s nats://host:4222 server info`
2. Fix host/port/credentials in the litestream replica URL config
3. Inspect the inner wrapped error for the specific cause (timeout, auth, TLS)
4. Check network/firewall/DNS between litestream and the NATS server

Example fix

// before
url: "nats://nats.internal:4222/backups"
// after (with credentials the server requires)
url: "nats://user:pass@nats.internal:4222/backups"

// before Init, verify the server accepts connections
conn, err := net.DialTimeout("tcp", "nats.example.com:4222", 3*time.Second)
if err != nil {
	return fmt.Errorf("NATS server unreachable: %w", err)
}
conn.Close()

if err := client.Init(ctx); err != nil {
	var netErr net.Error
	if errors.As(err, &netErr) {
		return fmt.Errorf("transient NATS outage, will retry: %w", err)
	}
	return err
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• failed to connect to NATS server: %w
• replica sync: %w
• shutdown sync timeout after %d attempts: %w
• fetch ltx files: %w
• cannot determine L%d max ltx file for %q: %w

AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06). Data as JSON: /api/errors/88f8189d86c92e5f. Report an issue: GitHub.