{"record":{"id":"e55c96fe624fa8e6","repo":"wavetermdev/waveterm","slug":"failed-to-start-new-job-w","errorCode":null,"errorMessage":"failed to start new job: %w","messagePattern":"failed to start new job: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/blockcontroller/durableshellcontroller.go","lineNumber":174,"sourceCode":"\t\t\tjobId = blockData.JobId\n\t\t} else if !force {\n\t\t\tlog.Printf(\"block %q has jobId %s but manager is not running (status: %s), not starting (force=false)\\n\", dsc.BlockId, blockData.JobId, status)\n\t\t\treturn nil\n\t\t} else {\n\t\t\tlog.Printf(\"block %q has jobId %s but manager is not running (status: %s), starting new job (force=true)\\n\", dsc.BlockId, blockData.JobId, status)\n\t\t\t// intentionally leave jobId empty to trigger starting a new job below\n\t\t}\n\t}\n\n\tif jobId == \"\" {\n\t\tlog.Printf(\"block %q starting new durable shell\\n\", dsc.BlockId)\n\t\tfsErr := filestore.WFS.MakeFile(ctx, dsc.BlockId, wavebase.BlockFile_Term, nil, wshrpc.FileOpts{MaxSize: DefaultTermMaxFileSize, Circular: true})\n\t\tif fsErr != nil && fsErr != fs.ErrExist {\n\t\t\treturn fmt.Errorf(\"error creating block term file: %w\", fsErr)\n\t\t}\n\t\tnewJobId, err := dsc.startNewJob(ctx, blockMeta, dsc.ConnName, rtOpts)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to start new job: %w\", err)\n\t\t}\n\t\tjobId = newJobId\n\t}\n\n\tdsc.WithLock(func() {\n\t\tdsc.JobId = jobId\n\t\tdsc.sendUpdate_withlock()\n\t})\n\n\terr = jobcontroller.ReconnectJob(ctx, jobId, rtOpts)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to reconnect to job: %w\", err)\n\t}\n\n\treturn nil\n}\n\nfunc (dsc *DurableShellController) Stop(graceful bool, newStatus string, destroy bool) {","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/blockcontroller/durableshellcontroller.go#L156-L192","documentation":"After provisioning the term file, Start launches the durable shell via dsc.startNewJob. This error wraps any failure from that call — job creation, connection/RPC to the remote, or command launch failure — so the shell never gets a jobId.","triggerScenarios":"startNewJob fails: connection to the remote is down or drops during launch, the remote job controller rejects the start, shell command invalid (bad rtOpts/shell type), or auth fails mid-launch.","commonSituations":"SSH connection unstable right when the terminal starts; invalid shell type in block runtime options; remote host refusing new sessions (MaxSessions, out of memory); wave client on the remote outdated.","solutions":["Reconnect the remote connection and retry Start","Check block runtime options (shell type, args) are valid for the remote host","Look at connection logs for the underlying startNewJob failure","Update wave on the remote host if version mismatch is suspected"],"exampleFix":"// before\nerr := dsc.Start(ctx, meta, rtOpts, true)\n// after\nif err := dsc.Start(ctx, meta, rtOpts, true); err != nil {\n    if isConnErr(err) {\n        time.Sleep(3 * time.Second)\n        err = dsc.Start(ctx, meta, rtOpts, true) // retry after reconnect\n    }\n}","handlingStrategy":"retry","validationCode":"if c := conncontroller.MaybeGetConn(opts); c == nil || c.DeriveConnStatus().Status != conncontroller.Status_Connected {\n    return errors.New(\"connect remote before starting durable shell\")\n}","typeGuard":null,"tryCatchPattern":"if err := dsc.Start(ctx, meta, rtOpts, true); err != nil && strings.Contains(err.Error(), \"failed to start new job\") {\n    // reconnect, verify shell opts, retry with backoff\n}","preventionTips":["Verify the remote connection is Connected before launching durable shells","Validate block runtime opts (shell type/args) per host","Keep wave versions in sync between client and remote hosts"],"tags":["job","durable-shell","remote","connection"],"backgroundTag":"job-start-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}