{"record":{"id":"ee2ae3556309a4d5","repo":"nats-io/nats-server","slug":"failed-to-be-ready-for-connections-after-s-start","errorCode":null,"errorMessage":"failed to be ready for connections after %s: startup did not complete","messagePattern":"failed to be ready for connections after (.+?): startup did not complete","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/server.go","lineNumber":4017,"sourceCode":"\t\tchk[\"websocket\"] = info{ok: (opts.Websocket.Port == 0 || s.websocket.listener != nil), err: s.websocket.listenerErr}\n\t\tchk[\"mqtt\"] = info{ok: (opts.MQTT.Port == 0 || s.mqtt.listener != nil), err: s.mqtt.listenerErr}\n\t\ts.mu.RUnlock()\n\n\t\tvar numOK int\n\t\tfor _, inf := range chk {\n\t\t\tif inf.ok {\n\t\t\t\tnumOK++\n\t\t\t}\n\t\t}\n\t\tif numOK == len(chk) {\n\t\t\t// In the case of DontListen option (no accept loop), we still want\n\t\t\t// to make sure that Start() has done all the work, so we wait on\n\t\t\t// that.\n\t\t\tif opts.DontListen {\n\t\t\t\tselect {\n\t\t\t\tcase <-s.startupComplete:\n\t\t\t\tcase <-time.After(d):\n\t\t\t\t\treturn fmt.Errorf(\"failed to be ready for connections after %s: startup did not complete\", d)\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn nil\n\t\t}\n\t\tif d > 25*time.Millisecond {\n\t\t\ttime.Sleep(25 * time.Millisecond)\n\t\t}\n\t}\n\n\tfailed := make([]string, 0, len(chk))\n\tfor name, inf := range chk {\n\t\tif inf.ok && inf.err != nil {\n\t\t\tfailed = append(failed, fmt.Sprintf(\"%s(ok, but %s)\", name, inf.err))\n\t\t}\n\t\tif !inf.ok && inf.err == nil {\n\t\t\tfailed = append(failed, name)\n\t\t}\n\t\tif !inf.ok && inf.err != nil {","sourceCodeStart":3999,"sourceCodeEnd":4035,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/server.go#L3999-L4035","documentation":"When running with `dont_listen` (in-process/server-embedded mode), there is no listener to probe, so ReadyForConnections polls s.startupComplete instead. If startup does not finish within the deadline, the caller gets this timeout error after %s (the waited duration).","triggerScenarios":"Calling s.ReadyForConnections(d) (or NewServer+Start in embedded mode) with opts.DontListen true while Start() has not signaled startupComplete within the timeout — e.g. slow option processing, account resolver stalls, or a deadlock in startup.","commonSituations":"Embedded nats-server in tests/applications where Start() blocks on a slow resolver (URL fetch timeouts) or the caller never called Start(); too-short timeout (e.g. ReadyForConnections(time.Second)) under heavy init; startup goroutine panicking before signaling.","solutions":["Ensure Start() was actually invoked and completes: check logs for startup errors before waiting","Increase the ReadyForConnections timeout or poll longer in embedded mode","Fix whatever blocks startup (e.g. resolver URL unreachable) — inspect the wrapped startup logs","Verify DontListen mode setup: with dont_listen the app must rely on in-process clients only"],"exampleFix":"// before\nif !s.ReadyForConnections(500 * time.Millisecond) { ... }\n// after\nif !s.ReadyForConnections(10 * time.Second) {\n    log.Fatalf(\"embedded server did not become ready\")\n}","handlingStrategy":"try-catch","validationCode":"// In embedded (dont_listen) mode, confirm Start() was called and give a generous deadline\nif !started.Flag(\"started\") {\n    return errors.New(\"call srv.Start() before ReadyForConnections\")\n}","typeGuard":null,"tryCatchPattern":"if !srv.ReadyForConnections(30 * time.Second) {\n    if opts.DontListen {\n        log.Printf(\"startup did not complete within deadline; inspect server logs for blocking startup (resolver, options)\")\n        srv.Shutdown()\n        return errors.New(\"embedded server startup timeout\")\n    }\n    return errors.New(\"server not ready\")\n}","preventionTips":["Always call Start() before ReadyForConnections in embedded mode","Use a timeout proportional to expected resolver latency (URL resolvers can take seconds)","Monitor server logs for panics during startup that prevent the completion signal","In tests, fail fast on !ReadyForConnections instead of hanging on in-process clients"],"tags":["nats-server","embedded","startup-timeout","dont-listen"],"backgroundTag":"server-startup-timeout","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}