wavetermdev/waveterm · error

timeout waiting for connserver to register

Error message

timeout waiting for connserver to register

What it means

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.

Source

Thrown at pkg/wslconn/wslconn.go:344

			}
			conn.ConnController = nil
		})
		waitErr = cmd.Wait()
		log.Printf("conn controller (%q) terminated: %v", conn.GetName(), waitErr)
	}()
	go func() {
		defer func() {
			panichandler.PanicHandler("wsl:StartConnServer:handleStdIOClient", recover())
		}()
		logName := fmt.Sprintf("wslconn:%s", conn.GetName())
		wshutil.HandleStdIOClient(logName, linesChan, inputPipeWrite)
	}()
	conn.Infof(ctx, "connserver started, waiting for route to be registered\n")
	regCtx, cancelFn := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancelFn()
	err = wshutil.DefaultRouter.WaitForRegister(regCtx, wshutil.MakeConnectionRouteId(conn.GetName()))
	if err != nil {
		return false, clientVersion, "", fmt.Errorf("timeout waiting for connserver to register")
	}
	time.Sleep(300 * time.Millisecond) // TODO remove this sleep (but we need to wait until connserver is "ready")
	conn.Infof(ctx, "connserver is registered and ready\n")
	return false, clientVersion, "", nil
}

type WshInstallOpts struct {
	Force        bool
	NoUserPrompt bool
}

var queryTextTemplate = strings.TrimSpace(`
Wave requires Wave Shell Extensions to be
installed on %q
to ensure a seamless experience.

Would you like to install them?
`)

View on GitHub (pinned to a4447c1563)

Solutions

1. Retry the connection — cold WSL startup is often transient; reconnect and try again
2. Check that wsh runs at all in the distro: execute the ConnServerCmdTemplate command manually inside WSL and watch for errors
3. Reinstall/update wsh in the distro (InstallWsh/UpdateWsh) in case the binary is broken
4. Verify system resources: WSL memory/CPU limits (wsl.conf, .wslconfig) and machine load that could slow startup beyond 5s

Example fix

// before: single attempt fails on cold distro
_, _, _, err := conn.StartConnServer(ctx, false)
// after: retry once after reconnect
_, _, _, err := conn.StartConnServer(ctx, false)
if err != nil && strings.Contains(err.Error(), "timeout waiting for connserver") {
    conn.Reconnect(ctx)
    _, _, _, err = conn.StartConnServer(ctx, false)
}

_, _, _, err := conn.StartConnServer(ctx, false)
if err != nil && strings.Contains(err.Error(), "timeout waiting for connserver to register") {
    time.Sleep(time.Second)
    _ = conn.Reconnect(ctx)
    _, _, _, err = conn.StartConnServer(ctx, false)
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• unable to obtain client info: %w
• error starting conn server: %w
• failed to list workspaces: %v
• failed to list blocks from all %d workspace(s)
• getting file info: %w

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/9692c0c96edd3088. Report an issue: GitHub.