hashicorp/nomad · error

missing deployment ID

Error message

missing deployment ID

What it means

Nomad's DeploymentStatus (GetDeployment) RPC performs a blocking query for one deployment by ID. The ID check runs inside the blocking-query run function, so an empty args.DeploymentID causes the query to fail immediately with this validation error instead of returning a nil deployment. It means the client sent a read for a deployment without specifying which one.

Source

Thrown at nomad/deployment_endpoint.go:63

	defer metrics.MeasureSince([]string{"nomad", "deployment", "get_deployment"}, time.Now())

	// Check namespace read-job permissions
	allowNsOp := acl.NamespaceValidator(acl.NamespaceCapabilityReadJob)
	aclObj, err := d.srv.ResolveACL(args)
	if err != nil {
		return err
	} else if !allowNsOp(aclObj, args.RequestNamespace()) {
		return structs.ErrPermissionDenied
	}

	// Setup the blocking query
	opts := blockingOptions{
		queryOpts: &args.QueryOptions,
		queryMeta: &reply.QueryMeta,
		run: func(ws memdb.WatchSet, state *state.StateStore) error {
			// Verify the arguments
			if args.DeploymentID == "" {
				return fmt.Errorf("missing deployment ID")
			}

			// Look for the deployment
			out, err := state.DeploymentByID(ws, args.DeploymentID)
			if err != nil {
				return err
			}

			// Re-check namespace in case it differs from request.
			if out != nil && !allowNsOp(aclObj, out.Namespace) {
				// hide this deployment, caller is not authorized to view it
				out = nil
			}

			// Setup the output
			reply.Deployment = out
			if out != nil {
				reply.Index = out.ModifyIndex

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Pass a concrete deployment ID: nomad deployment status <deployment-id>
2. Obtain the deployment ID from nomad job status <job> or GET /v1/job/<job>/deployments
3. Guard scripts: [ -n "$DEPLOY_ID" ] || exit 1 before calling
4. List all deployments (GET /v1/deployments) to locate the correct ID

Example fix

// before
nomad deployment status "$DEPLOY_ID"   // var empty -> missing deployment ID

// after
DEPLOY_ID=$(nomad job inspect web | jq -r '.DeploymentID // empty')
[ -n "$DEPLOY_ID" ] && nomad deployment status "$DEPLOY_ID"

if deploymentID == "" {
    deps, _ := client.Jobs().Deployments(jobID, nil)
    if len(deps) == 0 { return fmt.Errorf("job %s has no deployments", jobID) }
    deploymentID = deps[0].ID
}

func validDeploymentID(id string) bool {
    return uuid.Parse(id) == nil || id != ""
}

dep, _, err := client.Deployments().Get(id)
if err != nil {
    if strings.Contains(err.Error(), "missing deployment ID") {
        return nil, fmt.Errorf("deployment ID empty; derive it from the job")
    }
    return nil, err
}

When it happens

Trigger: Calling GET /v1/deployment/<id> or nomad deployment status with an empty/blank deployment ID; SDK calls leaving DeploymentID unset; jobs that never created a deployment whose IDs were sourced from empty template output.

Common situations: CI pipelines parsing the deployment ID from nomad job deploy status output that failed earlier; scripts where DEPLOY_ID env var is unset; watching a deployment that was autoredacted/never started.

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

• missing plugin ID
• missing plugin ID
• must specify at least one healthy/unhealthy allocation ID
• missing parameterized job ID
• root key ID is required

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