What causes "wrong gateway" in nats-io/nats-server?

Make `gateway { name }` identical on all servers meant to gateway to each other.

wrong gateway

Error message

wrong gateway

What it means

ErrWrongGateway is returned when a server receives a gateway CONNECT from a remote gateway whose destination name does not match this server's configured gateway name. Gateway connections are paired by name; a mismatch means the remote peer dialed the wrong cluster or the gateway names are inconsistent across the topology. The sentinel is also the fixture for NewErrorCtx tests (TestErrCtx) showing errors can carry extra context while keeping the same Error() string.

Source

Thrown at server/errors.go:162

	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")

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

	// ErrBadMsgHeader signals the parser detected a bad message header

View on GitHub (pinned to 3a66a489d2)

Solutions

Make `gateway { name }` identical on all servers meant to gateway to each other.
Check `gateway.gateways` entries: the `name` of each remote entry must match that cluster's configured gateway name.
After a rename, update every peer's config and rolling-restart the servers.
If gateways are intentionally different clusters, remove the wrong remote URL from the gateways list.

Example fix

// before (mismatch)
// clusterA: gateway { name: "east" } ; clusterB: gateway { name: "west" }, gateways: [{url: "nats://east:7222", name: "wst"}]
// after
// clusterB: gateway { name: "west", gateways: [{url: "nats://east:7222", name: "east"}] }

Defensive patterns

Strategy: validation

Validate before calling

// Before deploying, assert every server's gateway.name and every remote entry name match:
// for each config: gateway.name must equal the `name` field peers use in gateway.gateways[].

Try / catch

if err := waitForGateway(); err != nil {
    if errors.Is(err, ErrWrongGateway) {
        // log local vs remote gateway names from config and abort peering
    }
}

Prevention

Generate gateway configs from a single source of truth so names cannot diverge.
After renaming a gateway, update all peers' gateways[] entries in the same change.
Verify peering with `nats server request NGW` or server logs after rollout.
Use DNS/hostnames consistently so one cluster is not accidentally fronted by another.

When it happens

Trigger: A remote gateway configured with a different `gateway.name` connects to this server's gateway port; gateways list URLs of a cluster whose name differs from the remote name given in `gateway.gateways`; symmetric gateway configs where local name is spelled differently on each side.

Common situations: Renaming a gateway in one cluster's config but not its peers; load balancer fronting two different gateway clusters; typos in the gateway name (case/spacing) between sites.

Related errors

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