wavetermdev/waveterm · error

error: %v

Error message

error: %v

What it means

WaitForConnect returns this error when DeriveConnStatus reports Status_Error; the underlying connection failure message (status.Error) is embedded via 'error: %v'. It is the surface for whatever caused the WSL connection itself to fail (launch failure, exec error, etc.).

Source

Thrown at pkg/wslconn/wslconn.go:484

func (conn *WslConn) WaitForConnect(ctx context.Context) error {
	for {
		status := conn.DeriveConnStatus()
		if status.Status == Status_Connected {
			return nil
		}
		if status.Status == Status_Connecting {
			select {
			case <-ctx.Done():
				return fmt.Errorf("context timeout")
			case <-time.After(100 * time.Millisecond):
				continue
			}
		}
		if status.Status == Status_Init || status.Status == Status_Disconnected {
			return fmt.Errorf("disconnected")
		}
		if status.Status == Status_Error {
			return fmt.Errorf("error: %v", status.Error)
		}
		return fmt.Errorf("unknown status: %q", status.Status)
	}
}

// does not return an error since that error is stored inside of WslConn
func (conn *WslConn) Connect(ctx context.Context) error {
	var connectAllowed bool
	conn.WithLock(func() {
		if conn.Status == Status_Connecting || conn.Status == Status_Connected {
			connectAllowed = false
		} else {
			conn.Status = Status_Connecting
			conn.Error = ""
			connectAllowed = true
		}
	})
	log.Printf("Connect %s\n", conn.GetName())

View on GitHub (pinned to a4447c1563)

Solutions

1. Read the embedded status.Error message — it names the underlying failure; fix that first
2. Verify WSL works independently: run 'wsl -l -v' and 'wsl -d <distro> echo ok' from a shell
3. Confirm the distro name configured in Wave matches an installed WSL distro
4. If WSL is broken, repair it (wsl --update / reinstall distro) then reconnect

Example fix

// before: opaque handling
err := conn.WaitForConnect(ctx)
// after
if err != nil && strings.HasPrefix(err.Error(), "error: ") {
    log.Printf("connection failed with underlying error: %s", strings.TrimPrefix(err.Error(), "error: "))
}

// confirm WSL itself works before attempting a connection
if err := exec.Command("wsl", "-l", "-v").Run(); err != nil {
    return fmt.Errorf("WSL is not installed or broken: %w", err)
}

func isConnStatusError(err error) bool {
    return err != nil && strings.HasPrefix(err.Error(), "error: ")
}

if err := conn.WaitForConnect(ctx); err != nil {
    if isConnStatusError(err) {
        underlying := strings.TrimPrefix(err.Error(), "error: ")
        log.Printf("WSL connection failed: %s", underlying) // fix per underlying message
    }
}

When it happens

Trigger: Calling WaitForConnect while the WslConn is in Status_Error — e.g. wsl.exe failed to spawn, the distro command errored, or Connect internally captured an error and set Status_Error.

Common situations: WSL not installed or 'wsl' not on PATH; the requested distro name doesn't exist; WSL service crashed; corrupt distro; Windows-side permission problems launching wsl.exe.

Related errors

• not connected: %s
• wsl connection not found: %s
• failed to create process controller: %w
• GetDistro not implemented on this system
• context timeout

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