{"record":{"id":"5317ad15bf977287","repo":"wavetermdev/waveterm","slug":"connection-name-is-required","errorCode":null,"errorMessage":"connection name is required","messagePattern":"connection name is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/jobcontroller/jobcontroller.go","lineNumber":615,"sourceCode":"\t\treturn nil, fmt.Errorf(\"job is not connected (status: %s)\", jobConnStatus)\n\t}\n\n\treturn job, nil\n}\n\ntype StartJobParams struct {\n\tConnName string\n\tJobKind  string\n\tCmd      string\n\tArgs     []string\n\tEnv      map[string]string\n\tTermSize *waveobj.TermSize\n\tBlockId  string\n}\n\nfunc StartJob(ctx context.Context, params StartJobParams) (string, error) {\n\tif params.ConnName == \"\" {\n\t\treturn \"\", fmt.Errorf(\"connection name is required\")\n\t}\n\tif params.JobKind != JobKind_Shell && params.JobKind != JobKind_Task {\n\t\treturn \"\", fmt.Errorf(\"jobkind must be %q or %q\", JobKind_Shell, JobKind_Task)\n\t}\n\tif params.Cmd == \"\" {\n\t\treturn \"\", fmt.Errorf(\"command is required\")\n\t}\n\tif params.TermSize == nil {\n\t\tparams.TermSize = &waveobj.TermSize{Rows: 24, Cols: 80}\n\t}\n\n\tisConnected, err := conncontroller.IsConnected(params.ConnName)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"error checking connection status: %w\", err)\n\t}\n\tif !isConnected {\n\t\treturn \"\", fmt.Errorf(\"connection %q is not connected\", params.ConnName)\n\t}","sourceCodeStart":597,"sourceCodeEnd":633,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/jobcontroller/jobcontroller.go#L597-L633","documentation":"StartJob validates its StartJobParams before creating any job; the first check requires a non-empty ConnName. This error is thrown immediately when a caller attempts to start a job without specifying which connection it should run on.","triggerScenarios":"Calling StartJob (via StartRemoteShellJob or JobControllerStartJobCommand) with StartJobParams.ConnName == \"\".","commonSituations":"Wiring a UI form that defaults to 'local' but submits an empty string; forgetting to propagate the block's connection name into params; constructing params programmatically and omitting ConnName.","solutions":["Set params.ConnName to a valid connection name (use the block's connection or the default local connection name)","Validate params before calling StartJob","Ensure UI/API callers always populate ConnName from the block config","Default to the local connection explicitly rather than empty string"],"exampleFix":"// before\njobId, err := jobcontroller.StartJob(ctx, jobcontroller.StartJobParams{\n\tJobKind: jobcontroller.JobKind_Shell,\n\tCmd:     \"bash\",\n})\n// after\njobId, err := jobcontroller.StartJob(ctx, jobcontroller.StartJobParams{\n\tConnName: \"ssh://myhost\", // or conncontroller.DefaultConnectionName for local\n\tJobKind:  jobcontroller.JobKind_Shell,\n\tCmd:      \"bash\",\n})","handlingStrategy":"validation","validationCode":"func validateStartJobParams(p jobcontroller.StartJobParams) error {\n\tif p.ConnName == \"\" { return errors.New(\"connection name is required\") }\n\tif p.JobKind != jobcontroller.JobKind_Shell && p.JobKind != jobcontroller.JobKind_Task {\n\t\treturn errors.New(\"invalid jobkind\")\n\t}\n\tif p.Cmd == \"\" { return errors.New(\"command is required\") }\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set ConnName explicitly, defaulting to the local connection name instead of \"\"","Run param validation before invoking StartJob","In UIs, initialize the connection field from block config, never leave blank","Mirror StartJob's validation (ConnName, JobKind, Cmd) at the call site"],"tags":["validation","job-controller","parameter-missing"],"backgroundTag":"missing-required-argument","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}