{"record":{"id":"8b5a4046375e5f33","repo":"wavetermdev/waveterm","slug":"connection-q-not-found","errorCode":null,"errorMessage":"connection %q not found","messagePattern":"connection %q not found","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/blockcontroller/durableshellcontroller.go","lineNumber":243,"sourceCode":"}\n\nfunc (dsc *DurableShellController) startNewJob(ctx context.Context, blockMeta waveobj.MetaMapType, connName string, rtOpts *waveobj.RuntimeOpts) (string, error) {\n\ttermSize := waveobj.TermSize{\n\t\tRows: shellutil.DefaultTermRows,\n\t\tCols: shellutil.DefaultTermCols,\n\t}\n\tif rtOpts != nil && rtOpts.TermSize.Rows > 0 && rtOpts.TermSize.Cols > 0 {\n\t\ttermSize = rtOpts.TermSize\n\t}\n\tcmdStr := blockMeta.GetString(waveobj.MetaKey_Cmd, \"\")\n\tcwd := blockMeta.GetString(waveobj.MetaKey_CmdCwd, \"\")\n\topts, err := remote.ParseOpts(connName)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"invalid ssh remote name (%s): %w\", connName, err)\n\t}\n\tconn := conncontroller.MaybeGetConn(opts)\n\tif conn == nil {\n\t\treturn \"\", fmt.Errorf(\"connection %q not found\", connName)\n\t}\n\tconnRoute := wshutil.MakeConnectionRouteId(connName)\n\tremoteInfo, err := wshclient.RemoteGetInfoCommand(wshclient.GetBareRpcClient(), &wshrpc.RpcOpts{Route: connRoute, Timeout: 2000})\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"unable to obtain remote info from connserver: %w\", err)\n\t}\n\tshellType := shellutil.GetShellTypeFromShellPath(remoteInfo.Shell)\n\tswapToken := makeSwapToken(ctx, ctx, dsc.BlockId, blockMeta, connName, shellType)\n\tsockName := wavebase.GetPersistentRemoteSockName(wstore.GetClientId())\n\trpcContext := wshrpc.RpcContext{\n\t\tProcRoute: true,\n\t\tSockName:  sockName,\n\t\tBlockId:   dsc.BlockId,\n\t\tConn:      connName,\n\t}\n\tjwtStr, err := wshutil.MakeClientJWTToken(rpcContext)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"error making jwt token: %w\", err)","sourceCodeStart":225,"sourceCodeEnd":261,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/blockcontroller/durableshellcontroller.go#L225-L261","documentation":"After parsing SSH opts, startNewJob looks up the actual connection object via conncontroller.MaybeGetConn. This error means no connection with that name is currently registered — the remote profile parses but no live connection record exists for it. The shell cannot be started without a connection backing it.","triggerScenarios":"ParseOpts succeeded but MaybeGetConn returns nil: the remote was never connected, the connection was closed/removed, or the conn name refers to a stale profile entry.","commonSituations":"App restarted and connection registry not yet populated; remote profile deleted while a block still points at it; connection disconnect removed the conn entry.","solutions":["Establish the connection first (connect the remote in the UI / trigger a connect) before starting the shell.","Confirm the remote profile exists in connection settings.","Reconnect the remote and then restart the block.","If the profile is gone, re-point the block at an existing connection."],"exampleFix":"// before\ncontroller.Start(ctx, blockMeta, rtOpts, false) // conn \"dev-box\" never connected\n// after\nif conncontroller.MaybeGetConn(remote.ParseOptsMust(\"dev-box\")) == nil {\n    conncontroller.ConnectToConn(ctx, \"dev-box\") // establish first\n}\ncontroller.Start(ctx, blockMeta, rtOpts, false)","handlingStrategy":"validation","validationCode":"opts, _ := remote.ParseOpts(connName)\nif conncontroller.MaybeGetConn(opts) == nil {\n    return fmt.Errorf(\"connect to %q before starting the shell\", connName)\n}","typeGuard":null,"tryCatchPattern":"if err := controller.Start(ctx, meta, rtOpts, false); err != nil {\n    if strings.Contains(err.Error(), \"not found\") {\n        // trigger connect flow, then retry Start once\n    }\n    return err\n}","preventionTips":["Connect remotes explicitly before opening terminal blocks on them","Clean up blocks referencing deleted connections","Re-check connection registry after app restart"],"tags":["ssh","connection","remote","not-found"],"backgroundTag":"connection-not-found","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}