wavetermdev/waveterm · error

jobkind must be %q or %q

Error message

jobkind must be %q or %q

What it means

StartJob validates params.JobKind before doing any work and rejects anything that is not exactly JobKind_Shell ("shell") or JobKind_Task ("task"). The %q verbs wrap the valid constants in quotes so the developer can see the exact accepted values. This is a programming error by the caller, not a runtime/environment failure.

Source

Thrown at pkg/jobcontroller/jobcontroller.go:618

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

	jobId := uuid.New().String()
	jobAuthToken, err := utilfn.RandomHexString(32)

View on GitHub (pinned to a4447c1563)

Solutions

1. Set params.JobKind to jobcontroller.JobKind_Shell for interactive shells or jobcontroller.JobKind_Task for one-shot commands — never a raw string literal.
2. If the value comes from user input or config, validate it against the two constants before calling StartJob.
3. Check for a type mismatch after upgrading Wave Terminal (constant values/names may have changed).

Example fix

// before
params := jobcontroller.StartJobParams{ConnName: conn, JobKind: "shell", Cmd: "ls"}
// after
params := jobcontroller.StartJobParams{ConnName: conn, JobKind: jobcontroller.JobKind_Shell, Cmd: "ls"}

if params.JobKind != jobcontroller.JobKind_Shell && params.JobKind != jobcontroller.JobKind_Task {
    return fmt.Errorf("JobKind must be JobKind_Shell or JobKind_Task, got %q", params.JobKind)
}

func isValidJobKind(k string) bool {
    return k == jobcontroller.JobKind_Shell || k == jobcontroller.JobKind_Task
}

When it happens

Trigger: Calling StartJob (directly or via StartRemoteShellJob / JobControllerStartJobCommand) with StartJobParams.JobKind set to an empty string, a typo like "shel", a different casing ("Shell"), or a stale/removed job-kind constant.

Common situations: Hand-constructed StartJobParams in scripts or tests, enum values renamed in a Wave Terminal version upgrade, frontend sending an unvalidated job kind string through an RPC command.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• command is required
• 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/49b31cbb4e9d4955. Report an issue: GitHub.