nats-io/nats-server · error

server is not running

Error message

server is not running

What it means

ErrServerNotRunning signals that an operation was attempted while the server (or the subsystem handling the request) is not running. JetStream API request handling returns it when `s.sys == nil` — i.e., the server has no active system account/eventing and is effectively not serving (server/jetstream.go:1208) — and JetStream cluster internals treat it as a shutdown signal to abandon inflight catchup work (server/jetstream_cluster.go:4106).

Source

Thrown at server/errors.go:175

	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
	ErrBadMsgHeader = errors.New("bad message header detected")

	// ErrMsgHeadersNotSupported signals the parser detected a message header
	// but they are not supported on this server.
	ErrMsgHeadersNotSupported = errors.New("message headers not supported")

	// ErrNoRespondersRequiresHeaders signals that a client needs to have headers
	// on if they want no responders behavior.
	ErrNoRespondersRequiresHeaders = errors.New("no responders requires headers support")

	// ErrClusterNameConfigConflict signals that the options for cluster name in cluster and gateway are in conflict.
	ErrClusterNameConfigConflict = errors.New("cluster name conflicts between cluster and gateway definitions")

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Ensure the server is fully started (system account enabled) before issuing JetStream API calls.
2. Detect shutdown and stop retrying: treat ErrServerNotRunning as a terminal condition and reconnect to another node.
3. For embedded usage, gate calls on server readiness (e.g. s.ReadyForConnections(timeout)).
4. If it appears during shutdown tests, synchronize Shutdown() with in-flight request completion (WaitForShutdown).

Example fix

// before
info, _ := js.AccountInfo()
// after
if nc.Status() == nats.CONNECTED && srvReady {
    info, err := js.AccountInfo()
    if errors.Is(err, ErrServerNotRunning) { /* stop and reconnect */ }
}

// Gate calls on readiness:
if !srv.ReadyForConnections(10 * time.Second) { return errors.New("server not ready") }
// and check client state:
if nc.Status() != nats.CONNECTED { return errors.New("client not connected") }

info, err := js.AccountInfo()
if errors.Is(err, ErrServerNotRunning) {
    // treat as terminal for this node: backoff, then reconnect to another server
    time.Sleep(backoff)
    nc.Reconnect()
}

When it happens

Trigger: Calling JetStream account/API methods during server shutdown or before the system account/eventing is initialized; cluster message handlers running after the server was shut down; issuing API requests to a node that is being stopped.

Common situations: Monitoring/JetStream clients hitting a node mid-rolling-restart; embedded NATS servers queried before s.Start() completes or after Shutdown(); graceful shutdown racing with background JetStream maintenance.

Related errors

• max_ack_pending must be set to -1
• system account not setup
• stream missing
• consumer assignment or group missing
• consumer not found

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