nats-io/nats-server · error

failed to create connection

Error message

failed to create connection

What it means

When the server needs an in-process client connection (createJwtAccount / internal client setup), it creates a socketpair and starts the goroutine driving the client side via s.startGoRoutine. If the server is shutting down or the goroutine cannot be started, startGoRoutine returns false, both ends are closed, and this error is returned to the caller.

Source

Thrown at server/server.go:2893

		return s.listener, s.listenerErr
	}

	return natsListen("tcp", hp)
}

// InProcessConn returns an in-process connection to the server,
// avoiding the need to use a TCP listener for local connectivity
// within the same process. This can be used regardless of the
// state of the DontListen option.
func (s *Server) InProcessConn() (net.Conn, error) {
	pl, pr := net.Pipe()
	if !s.startGoRoutine(func() {
		s.createClientInProcess(pl)
		s.grWG.Done()
	}) {
		pl.Close()
		pr.Close()
		return nil, fmt.Errorf("failed to create connection")
	}
	return pr, nil
}

func (s *Server) acceptConnections(l net.Listener, acceptName string, createFunc func(conn net.Conn), errFunc func(err error) bool) {
	tmpDelay := ACCEPT_MIN_SLEEP

	for {
		conn, err := l.Accept()
		if err != nil {
			if errFunc != nil && errFunc(err) {
				return
			}
			if tmpDelay = s.acceptError(acceptName, err, tmpDelay); tmpDelay < 0 {
				break
			}
			continue
		}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Retry the operation after checking the server is running (s.IsRunning() / wait for readiness signal)
2. Ensure Shutdown is not racing the call — coordinate lifecycle with the startupComplete signal
3. In tests, start the server and wait for it to be ready before requesting in-process connections

// Only request in-process connections while the server is running
if !srv.IsRunning() || srv.IsQuitting() {
    return nil, errors.New("server not accepting internal connections")
}

pr, err := srv.createInternalAdminClient()
if err != nil {
    if strings.Contains(err.Error(), "failed to create connection") {
        time.Sleep(50 * time.Millisecond)
        pr, err = srv.createInternalAdminClient() // retry once after shutdown check
    }
    if err != nil { return err }
}

When it happens

Trigger: Calling code that requests an in-process connection while the server is quitting (s.isRunning false / quitting flag set), so startGoRoutine refuses to launch createClientInProcess and the pipe is torn down.

Common situations: Management API or tests requesting an internal connection concurrently with server Shutdown; server restart racing with connection creation; tests not waiting for server readiness before requesting internal connections.

Related errors

• attempted to connect to gateway port
• server is not running
• gsl: notification already registered
• error creating store for stream
• error creating store for consumer

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