hashicorp/nomad · error

job_submission requires a namespace

Error message

job_submission requires a namespace

What it means

setJobSubmission (state store helper persisting the JobSubmission object attached to a job) requires an explicit namespace since job submissions are namespaced entities. An empty namespace cannot scope the record, so the write is rejected.

Source

Thrown at nomad/state/state_store.go:5797

		return fmt.Errorf("UpsertScalingPolicies of policies failed: %v", err)
	}

	return nil
}

// updateJobSubmission stores the original job source and variables associated that the
// job structure originates from. It is up to the job submitter to include the source
// material, and as such sub may be nil, in which case nothing is stored.
func (s *StateStore) updateJobSubmission(index uint64, sub *structs.JobSubmission, namespace, jobID string, version uint64, txn *txn) error {
	// critical that we operate on a copy; the original must not be modified
	// e.g. in the case of job gc and its last second version bump
	sub = sub.Copy()

	switch {
	case sub == nil:
		return nil
	case namespace == "":
		return errors.New("job_submission requires a namespace")
	case jobID == "":
		return errors.New("job_submission requires a jobID")
	default:
		sub.Namespace = namespace
		sub.JobID = jobID
		sub.JobModifyIndex = index
		sub.Version = version
	}

	// check if we already have a submission for this (namespace, jobID, version)
	obj, err := txn.First("job_submission", "id", namespace, jobID, version)
	if err != nil {
		return err
	}
	if obj != nil {
		// if we already have a submission for this (namespace, jobID, version)
		// then there is nothing to do; manually avoid potential for duplicates
		return nil

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Default the namespace to structs.DefaultNamespace ("default") before invoking the state store call
2. Call the job Normalize/Canonicalize routine on the request before writing so Namespace is populated
3. Include the namespace explicitly in API requests (e.g. ?namespace=... or namespace field in the job JSON)

Example fix

// before
stateStore.UpsertJobSubmission(msgType, idx, txn, sub, "", jobID, index, version)
// after
ns := namespace
if ns == "" { ns = structs.DefaultNamespace }
stateStore.UpsertJobSubmission(msgType, idx, txn, sub, ns, jobID, index, version)

func ensureNamespace(ns string) string {
    if ns == "" { return structs.DefaultNamespace }
    return ns
}
// call: upsertJobSubmission(sub, ensureNamespace(ns), jobID, index, version)

func hasNamespace(j *structs.Job) bool {
    return j != nil && j.Namespace != ""
}

if err := upsert(sub, ns, jobID); err != nil && strings.Contains(err.Error(), "requires a namespace") {
    return upsert(sub, structs.DefaultNamespace, jobID)
}

When it happens

Trigger: Calling StateStore.JobSubmission setter (via the upsert job path or direct state store use) with namespace="", e.g. a caller forgetting to default the namespace before writing a job that carries a job_submission block.

Common situations: Custom tooling or embedded-Nomad code paths that bypass RPC-layer namespace defaulting (normally RPCs default to the "default" namespace); passing job structs around without Normalize routines that fill Namespace.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• job_submission requires a jobID
• Job must be in a namespace
• missing namespace
• can not target wildcard ("*")namespace
• validating volume %q against state failed: %v

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