{"record":{"id":"f2461babcf12832c","repo":"microsoft/FASTER","slug":"failed-to-connect-server","errorCode":null,"errorMessage":"Failed to connect server.","messagePattern":"Failed to connect server\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"cs/remote/src/FASTER.client/ClientSession.cs","lineNumber":684,"sourceCode":"        private Socket GetSendSocket(string address, int port, int millisecondsTimeout = -2)\n        {\n            var ip = IPAddress.Parse(address);\n            var endPoint = new IPEndPoint(ip, port);\n            var socket = new Socket(ip.AddressFamily, SocketType.Stream, ProtocolType.Tcp)\n            {\n                NoDelay = true\n            };\n\n            if (millisecondsTimeout != -2)\n            {\n                IAsyncResult result = socket.BeginConnect(endPoint, null, null);\n                result.AsyncWaitHandle.WaitOne(millisecondsTimeout, true);\n                if (socket.Connected)\n                    socket.EndConnect(result);\n                else\n                {\n                    socket.Close();\n                    throw new Exception(\"Failed to connect server.\");\n                }\n            }\n            else\n            {\n                socket.Connect(endPoint);\n            }\n\n            // Ok to create new event args on accept because we assume a connection to be long-running\n            var receiveEventArgs = new SocketAsyncEventArgs();\n            var bufferSize = BufferSizeUtils.ServerBufferSize(maxSizeSettings);\n            receiveEventArgs.SetBuffer(new byte[bufferSize], 0, bufferSize);\n            receiveEventArgs.UserToken =\n                new ClientNetworkSession<Key, Value, Input, Output, Context, Functions, ParameterSerializer>(socket, this);\n            receiveEventArgs.Completed += RecvEventArg_Completed;\n            var response = socket.ReceiveAsync(receiveEventArgs);\n            Debug.Assert(response);\n            return socket;\n        }","sourceCodeStart":666,"sourceCodeEnd":702,"githubUrl":"https://github.com/microsoft/FASTER/blob/321d872eabda6a0345c8bd76419f89723ed864ae/cs/remote/src/FASTER.client/ClientSession.cs#L666-L702","documentation":"The ClientSession constructor attempted an asynchronous TCP connect to the FASTER server with a timeout; when the wait completed, the socket was still not in the Connected state. The library closes the socket and throws, meaning the server was unreachable or refused/did not complete the handshake within the timeout.","triggerScenarios":"Calling new ClientSession(...) with a millisecondsTimeout where the server is down, listening on a different host/port, blocked by a firewall, or too slow to accept within the timeout.","commonSituations":"Wrong endpoint/IP or port in configuration; server process not started yet (startup ordering in docker-compose/k8s); firewall or security-group blocking the port; container networking/DNS misconfiguration; overloaded server exceeding the connect timeout.","solutions":["Verify the server endpoint (host/IP and port) matches the actual listening address of the FASTER server.","Ensure the server is up and listening before constructing the client (add startup/health-check ordering).","Increase the connect timeout argument, and retry connection with backoff.","Check network paths: firewalls, security groups, Docker/Kubernetes network policy, and DNS resolution."],"exampleFix":"// before\nvar session = new ClientSession<...>(endPoint, ...);\n\n// after: retry with backoff\nClientSession<...> session = null;\nfor (var attempt = 0; attempt < 5; attempt++)\n{\n    try { session = new ClientSession<...>(endPoint, ..., timeoutMs: 10000); break; }\n    catch (Exception) when (attempt < 4) { Thread.Sleep(1000 * (attempt + 1)); }\n}","handlingStrategy":"retry","validationCode":"// probe TCP reachability before constructing the session\nusing (var probe = new TcpClient())\n{\n    var ok = probe.ConnectAsync(host, port).Wait(5000);\n    if (!ok) throw new InvalidOperationException($\"FASTER server {host}:{port} unreachable\");\n}","typeGuard":null,"tryCatchPattern":"ClientSession<...> session = null;\nfor (var attempt = 0; attempt < 5 && session == null; attempt++)\n{\n    try { session = new ClientSession<...>(endPoint, ..., 10000); }\n    catch (Exception ex) when (ex.Message == \"Failed to connect server.\") { Thread.Sleep(2000 * (attempt + 1)); }\n}","preventionTips":["Add startup/health-check ordering so the server is listening before clients start.","Verify host/port configuration against the server's actual bind address.","Open firewall/security-group rules for the FASTER port.","Use a generous connect timeout plus exponential backoff retries."],"tags":["csharp","networking","tcp","connection","timeout"],"backgroundTag":"connection-refused","analyzedSha":"321d872eabda6a0345c8bd76419f89723ed864ae","analyzedAt":"2026-09-15T22:18:00.693Z","contentChangedAt":"2026-09-15T22:18:00.693Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}