hashicorp/nomad · error

job submission lookup failed: %v

Error message

job submission lookup failed: %v

What it means

This helper fetches a single JobSubmission by namespace, job name, and version using txn.FirstWatch. The error wraps a lookup failure on the job_submission table; it indicates the query errored (not merely that no submission exists, which returns nil,nil).

Source

Thrown at nomad/state/state_store.go:2317

	}
	ws.Add(iter.WatchCh())

	return iter, nil
}

// JobSubmission returns the original HCL/Variables context of a job, if available.
//
// Note: it is a normal case for the submission context to be unavailable, in which case
// nil is returned with no error.
func (s *StateStore) JobSubmission(ws memdb.WatchSet, namespace, jobName string, version uint64) (*structs.JobSubmission, error) {
	txn := s.db.ReadTxn()
	return s.jobSubmission(ws, namespace, jobName, version, txn)
}

func (s *StateStore) jobSubmission(ws memdb.WatchSet, namespace, jobName string, version uint64, txn Txn) (*structs.JobSubmission, error) {
	watchCh, existing, err := txn.FirstWatch("job_submission", "id", namespace, jobName, version)
	if err != nil {
		return nil, fmt.Errorf("job submission lookup failed: %v", err)
	}
	ws.Add(watchCh)
	if existing != nil {
		return existing.(*structs.JobSubmission), nil
	}
	return nil, nil
}

// JobByID is used to lookup a job by its ID. JobByID returns the current/latest job
// version.
func (s *StateStore) JobByID(ws memdb.WatchSet, namespace, id string) (*structs.Job, error) {
	txn := s.db.ReadTxn()
	return s.JobByIDTxn(ws, namespace, id, txn)
}

// JobByIDTxn is used to lookup a job by its ID, like  JobByID. JobByID returns the job version
// accessible through in the transaction
func (s *StateStore) JobByIDTxn(ws memdb.WatchSet, namespace, id string, txn Txn) (*structs.Job, error) {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped %v cause to find the underlying error
2. Retry the read; typically transient
3. If persistent, check state store health and report upstream

func isSubmissionLookupErr(err error) bool {
  return err != nil && strings.Contains(err.Error(), "job submission lookup failed")
}

sub, _, err := client.Jobs().Submission(jobID, ns, version)
if err != nil {
  if isSubmissionLookupErr(err) { /* query failure, retry */ } else { /* other */ }
}
// note: nil sub is not an error — submission may not exist

When it happens

Trigger: Calling JobSubmission (or JobSubmissionTxn) with a namespace/name/version where the internal FirstWatch query on job_submission 'id' index fails.

Common situations: Rare; seen in job read RPC paths when the underlying memdb query errors, e.g. during internal index issues.

Related errors

• job_submission requires a namespace
• job_submission requires a jobID
• unable to update job submission: %v
• error parsing: root should be an object
• cannot specify Accessor ID

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