apache/beam · error

error connecting to NATS

Error message

error connecting to NATS: %v

What it means

Setup for the NATS IO functions calls nats.Connect(fn.URI, opts...) to establish the client connection (optionally with credentials from fn.CredsFile). If the connection cannot be established, the error is wrapped with this message and Setup fails, aborting the DoFn lifecycle. It means the worker could not reach or authenticate to the NATS server.

Solutions

1. Verify fn.URI is reachable from the worker (nc URI should look like nats://host:4222) and the server is up
2. Check network/firewall rules and DNS from the Beam worker environment
3. Validate fn.CredsFile exists and holds valid NATS credentials; remove it if the server requires none
4. Increase nats.Connect timeouts/retries options if the server is slow to accept connections
5. Test connectivity independently (e.g. `nats --server <uri> status`) before running the pipeline

Example fix

// before
URI: "nats://nats.prod:4222" // host not resolvable from workers
// after
URI: "nats://nats.prod.internal:4222" // verified reachable; plus:
opts = append(opts, nats.RetryOnFailedConnect(true), nats.ConnectTimeout(10*time.Second))

// pre-flight check before starting the pipeline
conn, err := nats.Connect(uri, nats.Timeout(5*time.Second), nats.UserCredentials(credsFile))
if err != nil {
	return fmt.Errorf("NATS preflight connect failed for %s: %w", uri, err)
}
conn.Close()

func validNATSURI(uri string) bool {
	u, err := url.Parse(uri)
	return err == nil && (u.Scheme == "nats" || u.Scheme == "tls" || u.Scheme == "nats") && u.Host != ""
}

if err := fn.Setup(ctx); err != nil {
	var connErr *nats.Error
	if errors.As(err, &connErr) && connErr.Timeout() {
		// retry Setup with backoff
	}
	return fmt.Errorf("setup failed: %w", err)
}

When it happens

Trigger: nats.Connect returns an error: server unreachable at fn.URI, invalid credentials file, TLS handshake failure, auth mismatch, or connection timeout.

Common situations: Typo in NATS URI or wrong port; NATS server down or behind a firewall; stale or malformed .creds file passed via CredsFile; NATS cluster requiring auth but no credentials configured; DNS resolution failure in the Beam worker environment.

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

• err
• error connecting to job server at
• error connecting to MongoDB
• error creating JetStream context
• error fetching messages

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/0dba1f6601062edf. Report an issue: GitHub.

Appendix: source

Thrown at sdks/go/pkg/beam/io/natsio/common.go:45

	URI       string
	CredsFile string
	nc        *nats.Conn
	js        jetstream.JetStream
}

func (fn *natsFn) Setup() error {
	if fn.nc != nil && fn.js != nil {
		return nil
	}

	var opts []nats.Option
	if fn.CredsFile != "" {
		opts = append(opts, nats.UserCredentials(fn.CredsFile))
	}

	conn, err := nats.Connect(fn.URI, opts...)
	if err != nil {
		return fmt.Errorf("error connecting to NATS: %v", err)
	}
	fn.nc = conn

	js, err := jetstream.New(fn.nc)
	if err != nil {
		return fmt.Errorf("error creating JetStream context: %v", err)
	}
	fn.js = js

	return nil
}

func (fn *natsFn) Teardown() {
	if fn.nc != nil {
		fn.nc.Close()
	}
}

View on GitHub (pinned to 12126d8942)