hashicorp/nomad · error

failed to create job diff: %v

Error message

failed to create job diff: %v

What it means

During a job plan/diff operation, structs.Job.Diff(old, new, true) failed while building the JobDiff for the reply, and the endpoint wraps the internal error as 'failed to create job diff'. Diff can fail when the underlying job structs cannot be compared safely (e.g. malformed multiregion/update blocks), so this indicates corrupt or unexpected job data rather than a missing resource.

Source

Thrown at nomad/job_endpoint.go:1332

				if args.Diffs {
					for i := range out {
						var old, new *structs.Job
						new = out[i]

						if compareSpecificVersion {
							old = compareVersion
						} else {
							if i == len(out)-1 {
								// Skip the last version if not comparing to a specific version
								break
							}
							old = out[i+1]
						}

						d, err := old.Diff(new, true)
						if err != nil {
							return fmt.Errorf("failed to create job diff: %v", err)
						}
						reply.Diffs = append(reply.Diffs, d)
					}
				}
			} else {
				// Use the last index that affected the nodes table
				index, err := state.Index("job_version")
				if err != nil {
					return err
				}
				reply.Index = index
			}

			// Set the query response
			j.srv.setQueryMeta(&reply.QueryMeta)
			return nil
		}}
	return j.srv.blockingRPC(&opts)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped %v error to find which job field failed comparison.
2. Validate the job spec with 'nomad job validate' before submitting.
3. Re-submit/normalize the job so both versions use the current schema.
4. Upgrade Nomad if the error appears only on jobs persisted by an older version; if reproducible, file a bug with the wrapped error.

if _, _, err := client.Jobs().Validate(validateJob, nil); err != nil {
    return fmt.Errorf("job spec invalid before diff/plan: %w", err)
}

plan, _, err := client.Jobs().Scale(...)
if err != nil && strings.Contains(err.Error(), "failed to create job diff") {
    return fmt.Errorf("diff failed (%v); retry with Diffs disabled or validate the job spec", err)
}

When it happens

Trigger: Plan/Scale request with Diffs enabled where old.Diff(new, true) returns a non-nil error inside the diff loop at nomad/job_endpoint.go:1332.

Common situations: Submitting hand-crafted or API-generated job JSON with invalid nested blocks; state-store data from an older Nomad version lacking fields newer Diff logic expects; upgrades where persisted versions predate a schema change.

Related errors

• failed to serialize client_assertion jwt: %w
• error marshaling json for stream: %w
• error parsing: root should be an object
• missing policy name
• cannot specify Accessor ID

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