{"record":{"id":"9692c0c96edd3088","repo":"wavetermdev/waveterm","slug":"timeout-waiting-for-connserver-to-register-9692c0","errorCode":null,"errorMessage":"timeout waiting for connserver to register","messagePattern":"timeout waiting for connserver to register","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/wslconn/wslconn.go","lineNumber":344,"sourceCode":"\t\t\t}\n\t\t\tconn.ConnController = nil\n\t\t})\n\t\twaitErr = cmd.Wait()\n\t\tlog.Printf(\"conn controller (%q) terminated: %v\", conn.GetName(), waitErr)\n\t}()\n\tgo func() {\n\t\tdefer func() {\n\t\t\tpanichandler.PanicHandler(\"wsl:StartConnServer:handleStdIOClient\", recover())\n\t\t}()\n\t\tlogName := fmt.Sprintf(\"wslconn:%s\", conn.GetName())\n\t\twshutil.HandleStdIOClient(logName, linesChan, inputPipeWrite)\n\t}()\n\tconn.Infof(ctx, \"connserver started, waiting for route to be registered\\n\")\n\tregCtx, cancelFn := context.WithTimeout(context.Background(), 5*time.Second)\n\tdefer cancelFn()\n\terr = wshutil.DefaultRouter.WaitForRegister(regCtx, wshutil.MakeConnectionRouteId(conn.GetName()))\n\tif err != nil {\n\t\treturn false, clientVersion, \"\", fmt.Errorf(\"timeout waiting for connserver to register\")\n\t}\n\ttime.Sleep(300 * time.Millisecond) // TODO remove this sleep (but we need to wait until connserver is \"ready\")\n\tconn.Infof(ctx, \"connserver is registered and ready\\n\")\n\treturn false, clientVersion, \"\", nil\n}\n\ntype WshInstallOpts struct {\n\tForce        bool\n\tNoUserPrompt bool\n}\n\nvar queryTextTemplate = strings.TrimSpace(`\nWave requires Wave Shell Extensions to be\ninstalled on %q\nto ensure a seamless experience.\n\nWould you like to install them?\n`)","sourceCodeStart":326,"sourceCodeEnd":362,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/wslconn/wslconn.go#L326-L362","documentation":"After starting the connserver process, StartConnServer waits up to 5 seconds (context.WithTimeout) for the wshserver to register its route with wshutil.DefaultRouter. If WaitForRegister doesn't observe MakeConnectionRouteId(connName) within that window, the connection cannot be used for RPCs and this error is returned. It means the connserver process started but never became reachable over the router.","triggerScenarios":"Calling StartConnServer (via tryEnableWsh) when the remote connserver hangs or exits before registering; a slow/cold WSL distro startup taking longer than 5s; the connserver binary crashing immediately after printing its version; I/O pipes blocked so registration messages never reach the router.","commonSituations":"First connection to a freshly created WSL distro that is still initializing; heavily loaded machine where wshserver startup exceeds 5 seconds; wsh binary incompatible with the distro's libc/arch crashing at startup; antivirus or WSL networking issues stalling the process.","solutions":["Retry the connection — cold WSL startup is often transient; reconnect and try again","Check that wsh runs at all in the distro: execute the ConnServerCmdTemplate command manually inside WSL and watch for errors","Reinstall/update wsh in the distro (InstallWsh/UpdateWsh) in case the binary is broken","Verify system resources: WSL memory/CPU limits (wsl.conf, .wslconfig) and machine load that could slow startup beyond 5s"],"exampleFix":"// before: single attempt fails on cold distro\n_, _, _, err := conn.StartConnServer(ctx, false)\n// after: retry once after reconnect\n_, _, _, err := conn.StartConnServer(ctx, false)\nif err != nil && strings.Contains(err.Error(), \"timeout waiting for connserver\") {\n    conn.Reconnect(ctx)\n    _, _, _, err = conn.StartConnServer(ctx, false)\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"_, _, _, err := conn.StartConnServer(ctx, false)\nif err != nil && strings.Contains(err.Error(), \"timeout waiting for connserver to register\") {\n    time.Sleep(time.Second)\n    _ = conn.Reconnect(ctx)\n    _, _, _, err = conn.StartConnServer(ctx, false)\n}","preventionTips":["Retry once on cold WSL distro startup before surfacing an error to the user","Keep wsh in the distro current — old builds may fail to register","Ensure WSL has adequate memory/CPU limits so startup completes quickly","Check wshserver startup logs if timeouts repeat on a warm distro"],"tags":["wsl","wsh","timeout","connserver","rpc"],"backgroundTag":"connserver-register-timeout","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}