hashicorp/nomad · error

error looking up job version by tag: %v

Error message

error looking up job version by tag: %v

What it means

The Job.Versions (job versions diff) endpoint supports diffing against a tagged version: when args.DiffTagName is set, it calls state.JobVersionByTagName to resolve the tag to a version. This error wraps any internal state-store error from that lookup (distinct from a nil result, which yields 'tag not found').

Source

Thrown at nomad/job_endpoint.go:1281

			out, err := state.JobVersionsByID(ws, args.RequestNamespace(), args.JobID)
			if err != nil {
				return err
			}

			// Setup the output
			reply.Versions = out
			if len(out) != 0 {

				var compareVersionNumber uint64
				var compareVersion *structs.Job
				var compareSpecificVersion bool

				if args.Diffs {
					if args.DiffTagName != "" {
						compareSpecificVersion = true
						compareVersion, err = state.JobVersionByTagName(ws, args.RequestNamespace(), args.JobID, args.DiffTagName)
						if err != nil {
							return fmt.Errorf("error looking up job version by tag: %v", err)
						}
						if compareVersion == nil {
							return fmt.Errorf("tag %q not found", args.DiffTagName)
						}
						compareVersionNumber = compareVersion.Version
					} else if args.DiffVersion != nil {
						compareSpecificVersion = true
						compareVersionNumber = *args.DiffVersion
					}
				}

				// Note: a previous assumption here was that the 0th job was the latest, and that we don't modify "old" versions.
				// Adding version tags breaks this assumption (you can tag an old version, which should unblock /versions queries) so we now look for the highest ModifyIndex.
				var maxModifyIndex uint64
				for _, job := range out {
					if job.ModifyIndex > maxModifyIndex {
						maxModifyIndex = job.ModifyIndex
					}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped %v cause to identify the underlying state-store failure
2. Retry the request; transient snapshot issues can resolve on a second attempt
3. Drop the tag parameter and diff by version number (diff_version) instead
4. Check server logs for state-store/raft errors; restore or repair the state store if corruption is indicated

Example fix

// before
client.Jobs().Versions("web", true, &api.QueryOptions{Params: map[string]string{"tag": deploymentTag}})
// after
v, _, err := client.Jobs().Versions("web", true, nil) // diff by latest instead of by tag
if err != nil { return err }

// no client-side pre-check exists for tag-index state errors; detect and fall back
tag := q.Get("tag")
if tag != "" && !validTagPattern.MatchString(tag) { tag = "" }

versions, _, err := client.Jobs().Versions(jobID, true, qo)
if err != nil && strings.Contains(err.Error(), "error looking up job version by tag") {
	versions, _, err = client.Jobs().Versions(jobID, true, nil) // retry without tag
}

When it happens

Trigger: GET /v1/job/<id>/versions?diff=true&tag=<name> where the state store returns a non-nil error from the tag index lookup — e.g. store corruption, an internal index failure, or an unhandled query error, not simply a missing tag.

Common situations: Operators using 'nomad job inspect' style diff tooling with the tag parameter against a state store under stress or after a failed restore; clients passing malformed tag values that trip an unexpected store error.

Related errors

• could not query host volume: %w
• failed to query node pool: %v
• error parsing: root should be an object
• cannot specify Accessor ID
• network already configured but not found in state

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