hashicorp/nomad · error

command empty: %q

Error message

command empty: %q

What it means

validateCommand is a helper that rejects an empty command string passed to config fields that expect a single token (e.g. the entrypoint field), pointing the user to the companion args field. An all-whitespace command also triggers it because TrimSpace empties it.

Source

Thrown at drivers/docker/driver.go:1739

	if err != nil {
		err = fmt.Errorf("Failed to inspect container %s: %s", shimContainer.ID, err)

		// This error is always recoverable as it could
		// be caused by races between listing
		// containers and this container being removed.
		// See #2802
		return nil, nstructs.NewRecoverableError(err, true)
	}
	return &container, nil
}

// validateCommand validates that the command only has a single value and
// returns a user friendly error message telling them to use the passed
// argField.
func validateCommand(command, argField string) error {
	trimmed := strings.TrimSpace(command)
	if len(trimmed) == 0 {
		return fmt.Errorf("command empty: %q", command)
	}

	if len(trimmed) != len(command) {
		return fmt.Errorf("command contains extra white space: %q", command)
	}

	return nil
}

func (d *Driver) WaitTask(ctx context.Context, taskID string) (<-chan *drivers.ExitResult, error) {
	h, ok := d.tasks.Get(taskID)
	if !ok {
		return nil, drivers.ErrTaskNotFound
	}
	ch := make(chan *drivers.ExitResult)
	go d.handleWait(ctx, ch, h)
	return ch, nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Provide a non-empty command value in the driver config field.
2. Move the actual command/arguments into the args field instead of the single-token field.
3. Fix the template/variable so it renders a real value; or remove the field entirely to use the image default.

Example fix

// before
config {
  entrypoint = ""
}
// after
config {
  entrypoint = "/bin/myapp"
  args = ["--port", "8080"]
}

func commandPresent(v string) bool { return strings.TrimSpace(v) != "" }
// in CI: fail job registration if entrypoint/command fields are empty strings

When it happens

Trigger: A task sets a driver config field like `entrypoint = ""` (or only whitespace) while validateCommand checks it; StartTask fails during container config creation.

Common situations: Templated job files where a variable renders empty, users mistaking entrypoint for the full command list, copy-paste removing the value.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• does not match registry specification
• invalid cgroup permission string: %q
• invalid mount type, must be "bind", "volume", "tmpfs": %q
• command contains extra white space: %q
• missing secret ID

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