stride3d/stride · error · SimpleSocketException

Connection router did not connect back to our listen socket

Error message

Connection router did not connect back to our listen socket

What it means

InitiateConnectionToRouter throws SimpleSocketException when, after asking the router to connect back, no incoming socket arrives on the client's listening socket within 10 seconds (Task.Delay wins over the TaskCompletionSource). It means the router never dialed back.

Solutions

Verify the router can reach the client's listen socket (open firewall/NAT ports).
Check the client is listening on an address the router can connect to (not localhost in remote setups).
Confirm the router service is alive and processing requests.
Retry the initiate call; investigate logs if it times out repeatedly.

Example fix

// before
// listening on loopback, router on another machine
var ctx = await routerClient.InitiateConnectionToRouter("tcp://router:10000");
// after
var ctx = await routerClient.InitiateConnectionToRouter("tcp://router:10000", listenOnReachableExternalAddress);

Defensive patterns

Strategy: retry

Try / catch

try { ctx = await router.InitiateConnectionToRouter(url); }
catch (SimpleSocketException) { /* callback blocked: check firewall/NAT, retry */ }

Prevention

Open inbound firewall/NAT rules for the client's listen socket.
Listen on an externally reachable address, not loopback, for remote routers.
Monitor router health and retry connection initiation on timeout.

When it happens

Trigger: Requesting a connection to a router but the router (or its peer) fails to connect back to the client's listen socket within the 10-second window.

Common situations: Firewall/NAT blocking the router's callback connection to the client port; router overloaded or dead; client listen socket bound to an address unreachable by the router.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/3a8690b18191266a. Report an issue: GitHub.

Appendix: source

Thrown at sources/engine/Stride.Engine/Engine/Network/RouterClient.cs:117

                            socketContext.StartClient(serverAddress, DefaultPort);
                        }
                        catch (Exception) // Ideally we should filter SocketException, but not available on some platforms (maybe it should be wrapped in a type available on all paltforms?)
                        {
                            clientException = true;
                        }
                        if (clientException)
                        {
                            socketContext.StartServer(DefaultListenPort, true, 10);
                        }
                        break;
                    default:
                        throw new ArgumentOutOfRangeException();
                }

                // Connection should happen within 10 seconds, otherwise consider there is no connection router trying to connect back to us
                if (await Task.WhenAny(socketContextTCS.Task, Task.Delay(TimeSpan.FromSeconds(10))).ConfigureAwait(false) != socketContextTCS.Task)
                {
                    throw new SimpleSocketException("Connection router did not connect back to our listen socket");
                }

                return await socketContextTCS.Task;
            }
            catch (Exception e)
            {
                Log.Error($"Could not connect to connection router using mode {ConnectionMode}", e);
                throw;
            }
        }

        private static void StartControlConnection()
        {
            // Start control connection
            throw new NotImplementedException();
        }

        /// <summary>

View on GitHub (pinned to 96fad776d2)