gofr-dev/gofr · critical

connection error

Error message

connection error

What it means

errConnectionError (errors.go:21) is the sentinel returned when the NATS client cannot establish or re-establish its connection to the broker — used in establishConnection and the retryConnect path. It wraps the underlying dial failure so callers see a consistent connection error from gofr's NATS datasource. Exercised by TestClient_establishConnection and TestClient_retryConnect.

Source

Thrown at pkg/gofr/datasource/pubsub/nats/errors.go:21

import "errors"

var (
	// Client Errors.
	errServerNotProvided       = errors.New("client server address not provided")
	errSubjectsNotProvided     = errors.New("subjects not provided")
	errConsumerNotProvided     = errors.New("consumer name not provided")
	errConsumerCreationError   = errors.New("consumer creation error")
	errFailedToDeleteStream    = errors.New("failed to delete stream")
	errPublishError            = errors.New("publish error")
	errJetStreamNotConfigured  = errors.New("jStream is not configured")
	errJetStreamCreationFailed = errors.New("jStream creation failed")
	errJetStream               = errors.New("jStream error")
	errCreateStream            = errors.New("create stream error")
	errDeleteStream            = errors.New("delete stream error")
	errGetStream               = errors.New("get stream error")
	errCreateOrUpdateStream    = errors.New("create or update stream error")
	errHandlerError            = errors.New("handler error")
	errConnectionError         = errors.New("connection error")
	errSubscriptionError       = errors.New("subscription error")
)

View on GitHub (pinned to 187eb24962)

Solutions

1. Verify the NATS server URL(s) in config/env (host, port, scheme nats:// vs tls://) are correct and reachable (`nats conn -s $NATS_URL`).
2. Confirm the NATS server is running and listening (`nats server info`); restart it if down.
3. Check credentials/TLS: auth token, user/password, or client certs must match server configuration.
4. Increase reconnect options (RetryOnFailedConnect, MaxReconnects, backoff) or ensure retryConnect has time before failing fast.

Example fix

// before: unreachable server URL from stale env
// NATS_URL=nats://localhost:4222  (server runs elsewhere)
// after
// NATS_URL=nats://nats.default.svc.cluster.local:4222
if err := client.Connect(); err != nil {
    return fmt.Errorf("connect to NATS: %w", err)
}

u, err := url.Parse(cfg.NatsURL)
if err != nil || u.Scheme == "" || u.Host == "" {
    return fmt.Errorf("invalid NATS URL %q", cfg.NatsURL)
}
conn, err := net.DialTimeout("tcp", u.Host, 2*time.Second)
if err != nil {
    return fmt.Errorf("NATS host %s unreachable: %w", u.Host, err)
}
conn.Close()

if err := client.Connect(); err != nil {
    if errors.Is(err, errConnectionError) {
        // exponential backoff reconnect loop before giving up
        return retryConnect(client, 5)
    }
    return err
}

When it happens

Trigger: ConnectionManager Connect/establishConnection failing to dial the configured NATS server(s): wrong URL/host:port, server down, TLS/auth rejection, or all reconnect attempts exhausted in retryConnect.

Common situations: NATS_URL env var wrong or empty in the deployment environment; NATS cluster unreachable due to network policy/DNS; credentials or TLS certs rotated; server down during startup so initial connect fails.

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

• %w: creating index: %w
• %w: deleting index: %w
• %w: executing bulk: %w
• failed to dial FTP server %q: %w
• failed to fetch all organizations

AI-assisted analysis of gofr-dev/gofr@187eb24962 (2026-09-01). Data as JSON: /api/errors/26bc13a1fec9d164. Report an issue: GitHub.