nomad job stop: Stop and Purge Nomad Jobs in CI
nomad job stop deregisters a job, stopping all of its allocations, and optionally purges it from state.
Teardown steps and ephemeral environments use job stop. -purge removes the job entirely so its name is free to reuse.
What it does
nomad job stop marks a job as stopped: the scheduler drains and stops its allocations. The job definition stays in state (status dead) so its history is queryable, unless -purge removes it completely. By default the command watches the resulting evaluation.
Common usage
nomad job stop web
# remove the job from state entirely
nomad job stop -purge web
# stop without watching the eval
nomad job stop -detach webOptions
| Flag | What it does |
|---|---|
| -purge | Delete the job from state after stopping it |
| -detach | Return immediately without watching the eval |
| -global | Stop a multi-region job in all regions |
| -yes | Skip the interactive confirmation prompt |
| -namespace <ns> | Stop a job in a specific namespace |
In CI
Use -purge in ephemeral PR environments so the job name can be reused and stale dead jobs do not accumulate. Stopping an already-stopped job is harmless, keeping teardown idempotent.
Common errors in CI
"No job(s) with prefix or id ... found" on teardown is often fine (already gone); guard with || true if the job may not exist. "Error deregistering job: ... Permission denied" means the token lacks submit-job on the namespace. Without -purge the dead job lingers and re-running the same name reuses old version history.