nats-io/nats-server · error

attempted to connect to gateway port

Error message

attempted to connect to gateway port

What it means

ErrClientOrRouteConnectedToGatewayPort is returned when a plain client or route connection sends its CONNECT to a gateway listener. Gateway connections are expected to be from other servers and must include a `gateway` name in the CONNECT protocol (server/gateway.go:1002 rejects anything with `connect.Gateway == ""`). The server sends an error to the connection and closes it with the WrongPort reason.

Solutions

  1. Point the client at the client port (default 4222), not the gateway port (default 7222).
  2. Point cluster/routes at the cluster port (default 6222), not the gateway port.
  3. Audit server config so `port`, `cluster { port }` and `gateway { port }` are distinct and documented.
  4. If behind a proxy/LB, ensure the listener matches the protocol it forwards to.

Example fix

// before
nats.Connect("nats://gateway-host:7222")
// after
nats.Connect("nats://gateway-host:4222")
Defensive patterns

Strategy: validation

Validate before calling

// Validate the URL port before connecting:
func checkPort(raw string) error {
    u, err := url.Parse(raw)
    if err != nil { return err }
    p := u.Port()
    if p == "7222" { return fmt.Errorf("%s looks like a gateway port; use the client port (4222)", raw) }
    return nil
}

Try / catch

nc, err := nats.Connect(url)
if err != nil && strings.Contains(err.Error(), "attempted to connect to gateway port") {
    // fix URL to use client port and retry once
}

Prevention

When it happens

Trigger: Pointing a NATS client's servers URL at the gateway port; configuring a route (cluster) connection to the gateway port; any tool that dials the gateway port as if it were the normal client port.

Common situations: Port mix-ups in config where gateway.port equals client port or the client is given the gateway port; copy-pasting the gateway address into a client's `nats://` URL; deploying with load balancers that route to the wrong backend port.

Related errors

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/ef2cd5b3fc8fea4d. Report an issue: GitHub.

Appendix: source

Thrown at server/errors.go:157

	// ErrStreamImportBadPrefix is returned when a stream import prefix contains wildcards.
	ErrStreamImportBadPrefix = errors.New("stream import prefix can not contain wildcard tokens")

	// ErrStreamImportDuplicate is returned when a stream import is a duplicate of one that already exists.
	ErrStreamImportDuplicate = errors.New("stream import already exists")

	// ErrServiceImportAuthorization is returned when a service import is not authorized.
	ErrServiceImportAuthorization = errors.New("service import not authorized")

	// ErrImportFormsCycle is returned when an import would form a cycle.
	ErrImportFormsCycle = errors.New("import forms a cycle")

	// ErrCycleSearchDepth is returned when we have exceeded our maximum search depth..
	ErrCycleSearchDepth = errors.New("search cycle depth exhausted")

	// ErrClientOrRouteConnectedToGatewayPort represents an error condition when
	// a client or route attempted to connect to the Gateway port.
	ErrClientOrRouteConnectedToGatewayPort = errors.New("attempted to connect to gateway port")

	// ErrWrongGateway represents an error condition when a server receives a connect
	// request from a remote Gateway with a destination name that does not match the server's
	// Gateway's name.
	ErrWrongGateway = errors.New("wrong gateway")

	// ErrGatewayNameHasSpaces signals that the gateway name contains spaces, which is not allowed.
	ErrGatewayNameHasSpaces = errors.New("gateway name cannot contain spaces")

	// ErrNoSysAccount is returned when an attempt to publish or subscribe is made
	// when there is no internal system account defined.
	ErrNoSysAccount = errors.New("system account not setup")

	// ErrRevocation is returned when a credential has been revoked.
	ErrRevocation = errors.New("credentials have been revoked")

	// ErrServerNotRunning is used to signal an error that a server is not running.
	ErrServerNotRunning = errors.New("server is not running")

View on GitHub (pinned to 3a66a489d2)