What causes "command cannot be empty" in hashicorp/nomad?

Add a non-empty `command` to the action block in the job spec (e.g. `command = "/bin/sh"` with args).

command cannot be empty

Error message

command cannot be empty

What it means

JobAction.Validate() in nomad/structs/actions.go validates a job action definition. Every action must have a Command, so an empty Command field produces "command cannot be empty". The check exists because an action without a command has no executable semantics and would be unusable at runtime.

Source

Thrown at nomad/structs/actions.go:86

	if a == nil && o == nil {
		return true
	}
	if a == nil || o == nil {
		return false
	}
	return a.Name == o.Name &&
		a.Command == o.Command &&
		slices.Equal(a.Args, o.Args)
}

func (a *Action) Validate() error {
	if a == nil {
		return nil
	}

	var mErr *multierror.Error
	if a.Command == "" {
		mErr = multierror.Append(mErr, errors.New("command cannot be empty"))
	}
	if !validJobActionName.MatchString(a.Name) {
		mErr = multierror.Append(mErr, fmt.Errorf("invalid name '%s'", a.Name))
	}

	return mErr.ErrorOrNil()
}

View on GitHub (pinned to 482b49bf1a)

Solutions

Add a non-empty `command` to the action block in the job spec (e.g. `command = "/bin/sh"` with args).
If the command is templated, check the rendered job file (nomad job inspect / plan) to confirm the variable resolved.
Validate the JobAction struct client-side before submission: if a.Command == "" reject early with a clearer message.

Example fix

// HCL before
action "debug" {
  args = ["-c", "ps aux"]
}

// HCL after
action "debug" {
  command = "/bin/sh"
  args    = ["-c", "ps aux"]
}

Defensive patterns

Strategy: validation

Validate before calling

if action.Command == "" {
    return fmt.Errorf("action %q requires a command", action.Name)
}

Try / catch

if _, err := jobs.Validate(); err != nil {
    if strings.Contains(err.Error(), "command cannot be empty") {
        return fmt.Errorf("an action block in the jobspec is missing its command")
    }
    return err
}

Prevention

Always include both command and args in every action block in HCL.
Run `nomad job validate <file>` before submitting templated jobs.
Inspect rendered templates to ensure variables feeding `command` resolved to non-empty values.

When it happens

Trigger: Submitting a job (jobs parse/validate path) whose task group or task defines an `action` block with a name but no `command` attribute, e.g. HCL `action "shell" {}` or an equivalent JobAction struct with Command: "".

Common situations: Hand-writing HCL job files and omitting the command line; templating that renders an empty command from missing variables; upgrading Nomad where actions became stricter.

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

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/259027487fab9806. Report an issue: GitHub.