wavetermdev/waveterm · error

connection name is required

Error message

connection name is required

What it means

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.

Source

Thrown at pkg/jobcontroller/jobcontroller.go:615

		return nil, fmt.Errorf("job is not connected (status: %s)", jobConnStatus)
	}

	return job, nil
}

type StartJobParams struct {
	ConnName string
	JobKind  string
	Cmd      string
	Args     []string
	Env      map[string]string
	TermSize *waveobj.TermSize
	BlockId  string
}

func StartJob(ctx context.Context, params StartJobParams) (string, error) {
	if params.ConnName == "" {
		return "", fmt.Errorf("connection name is required")
	}
	if params.JobKind != JobKind_Shell && params.JobKind != JobKind_Task {
		return "", fmt.Errorf("jobkind must be %q or %q", JobKind_Shell, JobKind_Task)
	}
	if params.Cmd == "" {
		return "", fmt.Errorf("command is required")
	}
	if params.TermSize == nil {
		params.TermSize = &waveobj.TermSize{Rows: 24, Cols: 80}
	}

	isConnected, err := conncontroller.IsConnected(params.ConnName)
	if err != nil {
		return "", fmt.Errorf("error checking connection status: %w", err)
	}
	if !isConnected {
		return "", fmt.Errorf("connection %q is not connected", params.ConnName)
	}

View on GitHub (pinned to a4447c1563)

Solutions

1. Set params.ConnName to a valid connection name (use the block's connection or the default local connection name)
2. Validate params before calling StartJob
3. Ensure UI/API callers always populate ConnName from the block config
4. Default to the local connection explicitly rather than empty string

Example fix

// before
jobId, err := jobcontroller.StartJob(ctx, jobcontroller.StartJobParams{
	JobKind: jobcontroller.JobKind_Shell,
	Cmd:     "bash",
})
// after
jobId, err := jobcontroller.StartJob(ctx, jobcontroller.StartJobParams{
	ConnName: "ssh://myhost", // or conncontroller.DefaultConnectionName for local
	JobKind:  jobcontroller.JobKind_Shell,
	Cmd:      "bash",
})

func validateStartJobParams(p jobcontroller.StartJobParams) error {
	if p.ConnName == "" { return errors.New("connection name is required") }
	if p.JobKind != jobcontroller.JobKind_Shell && p.JobKind != jobcontroller.JobKind_Task {
		return errors.New("invalid jobkind")
	}
	if p.Cmd == "" { return errors.New("command is required") }
	return nil
}

When it happens

Trigger: Calling StartJob (via StartRemoteShellJob or JobControllerStartJobCommand) with StartJobParams.ConnName == "".

Common situations: 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.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Image too large (>5MB)
• Unsupported or invalid image type: ${blob.type}
• Invalid CSS color: ${String(color)}
• Invalid CSS color: ${color}
• ai:model is required

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