hashicorp/nomad · error

force launch for job %q failed: %v

Error message

force launch for job %q failed: %v

What it means

This error is returned by the Periodic.ForceLaunch RPC handler when forcing an immediate launch of a periodic job fails. It wraps the error from the server's periodicDispatcher.ForceEval call, which creates an evaluation to run the job now. It means the dispatcher refused or failed to schedule the forced run, not that the RPC itself was malformed (a non-periodic job is rejected earlier with a distinct message).

Source

Thrown at nomad/periodic_endpoint.go:80

	}

	ws := memdb.NewWatchSet()
	job, err := snap.JobByID(ws, args.RequestNamespace(), args.JobID)
	if err != nil {
		return err
	}
	if job == nil {
		return fmt.Errorf("job not found")
	}

	if !job.IsPeriodic() {
		return fmt.Errorf("can't force launch non-periodic job")
	}

	// Force run the job.
	eval, err := p.srv.periodicDispatcher.ForceEval(args.RequestNamespace(), job.ID)
	if err != nil {
		return fmt.Errorf("force launch for job %q failed: %v", job.ID, err)
	}

	reply.EvalID = eval.ID
	reply.EvalCreateIndex = eval.CreateIndex
	reply.Index = eval.CreateIndex
	return nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify the periodic job still exists and is enabled with `nomad job status <job>` before forcing
2. Retry the force launch after a short delay (dispatcher state may be rebuilding after a leader election)
3. Re-register the periodic job (`nomad job run <file>`) and then force launch
4. Check server logs for the underlying dispatcher error to identify deregistration vs internal failure

Example fix

// before
nomad job periodic force my-job
// after
nomad job status my-job || nomad job run my-job.nomad
nomad job periodic force my-job

status, _, err := client.Jobs().Info(jobID, nil)
if err != nil || status == nil {
    // job missing; re-register before forcing
}
// also confirm job.Periodic != nil before calling ForceLaunch

func isForceLaunchErr(err error) bool {
    return err != nil && strings.Contains(err.Error(), "force launch for job")
}

eval, _, err := client.Jobs().Periodic().ForceLaunch(jobID, nil)
if err != nil {
    if strings.Contains(err.Error(), "force launch for job") {
        time.Sleep(2 * time.Second) // retry; dispatcher may be rebuilding after leader election
        eval, _, err = client.Jobs().Periodic().ForceLaunch(jobID, nil)
    }
    if err != nil { return err }
}

When it happens

Trigger: Calling Periodic.ForceLaunch (nomad job periodic force or the Force public method) on a periodic job whose ID is not registered with the server's periodic dispatcher — e.g. the job was just deregistered, the leader changed and dispatcher state is being rebuilt, or the dispatcher no longer tracks the job.

Common situations: Race between job deregistration and a force-launch call; operator scripting `nomad job periodic force` against a job that was just removed; leadership transitions in a busy cluster; stale CLI caching a job ID after it was purged.

Related errors

• evaluation not blocked
• eval %s is not safe to delete
• failed to add job %v: %v
• failed to remove tracked job %q (%s): %v
• no servers

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