{"record":{"id":"78820d26b639ceeb","repo":"wavetermdev/waveterm","slug":"wsl-connection-not-found-s","errorCode":null,"errorMessage":"wsl connection not found: %s","messagePattern":"wsl connection not found: (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/blockcontroller/shellcontroller.go","lineNumber":341,"sourceCode":"\tConnName   string\n\tConnType   string\n\tSshConn    *conncontroller.SSHConn\n\tWslConn    *wslconn.WslConn\n\tWshEnabled bool\n\tShellPath  string\n\tShellOpts  []string\n\tShellType  string\n\tHomeDir    string\n}\n\nfunc (bc *ShellController) getConnUnion(logCtx context.Context, remoteName string, blockMeta waveobj.MetaMapType) (ConnUnion, error) {\n\trtn := ConnUnion{ConnName: remoteName}\n\twshEnabled := !blockMeta.GetBool(waveobj.MetaKey_CmdNoWsh, false)\n\tif strings.HasPrefix(remoteName, \"wsl://\") {\n\t\twslName := strings.TrimPrefix(remoteName, \"wsl://\")\n\t\twslConn := wslconn.GetWslConn(wslName)\n\t\tif wslConn == nil {\n\t\t\treturn ConnUnion{}, fmt.Errorf(\"wsl connection not found: %s\", remoteName)\n\t\t}\n\t\tconnStatus := wslConn.DeriveConnStatus()\n\t\tif connStatus.Status != conncontroller.Status_Connected {\n\t\t\treturn ConnUnion{}, fmt.Errorf(\"wsl connection %s not connected, cannot start shellproc\", remoteName)\n\t\t}\n\t\trtn.ConnType = ConnType_Wsl\n\t\trtn.WslConn = wslConn\n\t\trtn.WshEnabled = wshEnabled && wslConn.WshEnabled.Load()\n\t} else if conncontroller.IsLocalConnName(remoteName) {\n\t\trtn.ConnType = ConnType_Local\n\t\trtn.WshEnabled = wshEnabled\n\t} else {\n\t\topts, err := remote.ParseOpts(remoteName)\n\t\tif err != nil {\n\t\t\treturn ConnUnion{}, fmt.Errorf(\"invalid ssh remote name (%s): %w\", remoteName, err)\n\t\t}\n\t\tconn := conncontroller.MaybeGetConn(opts)\n\t\tif conn == nil {","sourceCodeStart":323,"sourceCodeEnd":359,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/blockcontroller/shellcontroller.go#L323-L359","documentation":"When the block's target remote uses the wsl:// scheme, getConnUnion resolves the named WSL distribution via wslconn.GetWslConn. This error means no WSL connection/distribution with that name is registered — the distro name in meta:conn doesn't match any known WSL instance on this machine.","triggerScenarios":"remoteName has the wsl:// prefix and wslconn.GetWslConn(trimmedName) returns nil: distribution uninstalled, name mismatch (case/space), WSL not enumerating distros, or a stale meta:conn after the distro was removed.","commonSituations":"User removed a WSL distro (wsl --unregister) but a terminal block still references it; WSL service not running / freshly booted before distros enumerate; typo in distro name; WSL1 vs WSL2 naming differences.","solutions":["Run `wsl -l -v` to list installed distributions and match the exact name (including case).","Reinstall/register the missing distro, or re-point the block's meta:conn at an existing one.","Ensure the WSL service is running and distros enumerate (wsl --status).","Trim typos/whitespace from the distro name in the block settings."],"exampleFix":"// before\nmeta := waveobj.MetaMapType{\"conn\": \"wsl://Ubuntu-20.04\"} // uninstalled distro\n// after\nmeta := waveobj.MetaMapType{\"conn\": \"wsl://Ubuntu-22.04\"} // name matching `wsl -l`","handlingStrategy":"validation","validationCode":"wslName := strings.TrimPrefix(remoteName, \"wsl://\")\nif wslconn.GetWslConn(wslName) == nil {\n    return fmt.Errorf(\"distro %q not found; run 'wsl -l -v' to list valid names\", wslName)\n}","typeGuard":null,"tryCatchPattern":"if err := controller.Start(ctx, meta, rtOpts, false); err != nil {\n    if strings.Contains(err.Error(), \"wsl connection not found\") {\n        // refresh WSL distro list, prompt user to re-pick a distro\n    }\n    return err\n}","preventionTips":["Pick WSL distros from the enumerated list, not free text","Re-point blocks after unregistering distributions","Verify WSL service health on boot before starting wsl:// blocks"],"tags":["wsl","connection","not-found","config"],"backgroundTag":"wsl-connection-not-found","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}