wavetermdev/waveterm · error

command is required

Error message

command is required

What it means

StartJob requires a non-empty Cmd in StartJobParams; an empty command has nothing to execute on the remote connection, so the call is rejected up front. It is a plain argument-validation failure thrown before any connection or database work.

Source

Thrown at pkg/jobcontroller/jobcontroller.go:621

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)
	}

	jobId := uuid.New().String()
	jobAuthToken, err := utilfn.RandomHexString(32)
	if err != nil {
		return "", fmt.Errorf("failed to generate job auth token: %w", err)
	}

View on GitHub (pinned to a4447c1563)

Solutions

1. Provide the command to run in params.Cmd (e.g. "bash -l" for a shell job or the actual task command).
2. Trim and check the command string at the call site before invoking StartJob.
3. If the command is user-supplied, surface a validation message in the UI instead of letting the RPC fail.

Example fix

// before
p.Cmd = cfg.Cmd // may be ""
// after
if strings.TrimSpace(cfg.Cmd) == "" { return errors.New("cmd must not be empty") }
p.Cmd = cfg.Cmd

if strings.TrimSpace(params.Cmd) == "" {
    return errors.New("StartJobParams.Cmd must not be empty")
}

When it happens

Trigger: Calling StartJob (or StartRemoteShellJob / JobControllerStartJobCommand) with StartJobParams.Cmd == "" — e.g. a shell job created without a command string, or a task whose command was never populated from config/UI.

Common situations: Frontend submits a block with an empty command line, config file has a blank cmd field, a variable interpolation in the command string resolved to empty string.

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

• jobkind must be %q or %q
• invalid mode %q (expected %q or %q)
• no arguments. wsh editor requires a file or URL as an argum
• too many arguments. wsh editor requires exactly one argumen
• Image too large (>5MB)

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