nomad job run: Usage, Options & Common CI Errors

Submit a job specification to a Nomad cluster for scheduling.

nomad job run registers a job with Nomad, which schedules its tasks across the cluster. In CI it is how you deploy services and batch jobs, authenticating with NOMAD_ADDR and an ACL token.

What it does

nomad job run <file.nomad.hcl> submits a job spec to the Nomad servers, which create an evaluation, place allocations on eligible clients, and roll out the deployment. The command streams placement results and (for service jobs) deployment progress until it completes or fails.

Common usage

# Submit a job spec
nomad job run webapp.nomad.hcl

# Dry-run placement without submitting
nomad job plan webapp.nomad.hcl

# Safe submit guarded by the plan’s modify index
nomad job run -check-index=42 webapp.nomad.hcl

Common error in CI: no address / placement failed

run fails with "Error querying ... no Nomad servers" (NOMAD_ADDR unset/unreachable), "ACL token required" (ACLs on), or "Placement Failures" when no client meets the constraints/resources. Fix: set NOMAD_ADDR and NOMAD_TOKEN, and for placement failures read the evaluation (nomad eval status -verbose <id>) to see whether it is missing resources, a failed constraint, or no eligible nodes - then fix the constraint, add capacity, or relax resource asks. Use nomad job plan in CI to catch issues before run.

Key options

Related guides