benbjohnson/litestream · error

failed to create JetStream context: %w

Error message

failed to create JetStream context: %w

What it means

After a successful NATS connection, connect() creates a JetStream context with jetstream.New(nc). This error wraps that failure. It means the NATS client library could not initialize JetStream — nearly always because JetStream is disabled or unsupported on the connected server.

Source

Thrown at nats/replica_client.go:165

	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()...)
	if err != nil {
		return fmt.Errorf("failed to connect to NATS server: %w", err)
	}

	js, err := jetstream.New(nc)
	if err != nil {
		nc.Close()
		return fmt.Errorf("failed to create JetStream context: %w", err)
	}

	c.nc = nc
	c.js = js
	return nil
}

func (c *ReplicaClient) options() []nats.Option {
	opts := []nats.Option{
		nats.MaxReconnects(c.MaxReconnects),
		nats.ReconnectWait(c.ReconnectWait),
		nats.ReconnectJitter(c.ReconnectJitter, c.ReconnectJitter*2),
		nats.Timeout(c.Timeout),
		nats.PingInterval(c.PingInterval),
		nats.MaxPingsOutstanding(c.MaxPingsOut),
		nats.ReconnectBufSize(c.ReconnectBufSize),
	}

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Enable JetStream in nats-server config and restart: jetstream { store_dir: "/data/jetstream" }
2. Verify with `nats -s <url> server info` that JetStream reports enabled/available
3. Upgrade nats-server if the version lacks JetStream support
4. Check account/operator JetStream limits if using a managed NATS

Example fix

// nats-server.conf
// before
port: 4222
// after
port: 4222
jetstream {
  store_dir: "/var/lib/nats/jetstream"
}

// verify JetStream is enabled before configuring litestream
info, err := exec.Command("nats", "-s", natsURL, "server", "info").Output()
if err != nil || !strings.Contains(string(info), "JetStream") {
	return fmt.Errorf("enable JetStream in nats-server config")
}

if err := client.Init(ctx); err != nil {
	if strings.Contains(err.Error(), "failed to create JetStream context") {
		return fmt.Errorf("JetStream unavailable on server; enable jetstream { } in nats-server.conf: %w", err)
	}
	return err
}

When it happens

Trigger: jetstream.New(nc) returns an error inside connect() (called by Init): server started without JetStream enabled, server version too old for the jetstream client API, or the account lacks JetStream usage rights.

Common situations: Default nats-server config without `jetstream { enabled: true }`; embedded/old NATS servers without JetStream; operator/account JetStream disabled in a managed NATS.

Related errors

• nats: failed to initialize object store: %w
• invalid NATS URL: %w
• invalid scheme for NATS replica: %s
• bucket required for NATS replica
• client-cert and client-key must both be specified for mutual

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