Tagged version description must be under 1000 characters, cu

Error message

Tagged version description must be under 1000 characters, currently %d

What it means

Job.Validate() enforces the same 1000-character limit (MaxDescriptionCharacters) on j.VersionTag.Description, appending this error when exceeded. Version tags annotate job versions in the UI, and their descriptions are size-bounded.

Source

Thrown at nomad/structs/structs.go:4820

	} else {
		for idx, spread := range j.Spreads {
			if err := spread.Validate(); err != nil {
				outer := fmt.Errorf("Spread %d validation failed: %s", idx+1, err)
				mErr.Errors = append(mErr.Errors, outer)
			}
		}
	}

	const MaxDescriptionCharacters = 1000
	if j.UI != nil {
		if len(j.UI.Description) > MaxDescriptionCharacters {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("UI description must be under 1000 characters, currently %d", len(j.UI.Description)))
		}
	}

	if j.VersionTag != nil {
		if len(j.VersionTag.Description) > MaxDescriptionCharacters {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("Tagged version description must be under 1000 characters, currently %d", len(j.VersionTag.Description)))
		}
	}

	// Check for duplicate task groups
	taskGroups := make(map[string]int)
	for idx, tg := range j.TaskGroups {
		if tg.Name == "" {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("Job task group %d missing name", idx+1))
		} else if existing, ok := taskGroups[tg.Name]; ok {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("Job task group %d redefines '%s' from group %d", idx+1, tg.Name, existing+1))
		} else {
			taskGroups[tg.Name] = idx
		}

		if tg.ShutdownDelay != nil && *tg.ShutdownDelay < 0 {
			mErr.Errors = append(mErr.Errors, errors.New("ShutdownDelay must be a positive value"))
		}

View on GitHub (pinned to 482b49bf1a)

Solutions

Shorten VersionTag.Description below 1000 characters
Summarize the change and link to full details externally
Truncate programmatically in the CI templating step
Validate the job spec with 'nomad job validate' before submit

Example fix

// before
version_tag {
  description = "<full 1500-char commit message>"
}
// after
version_tag {
  description = "feat: add retry logic (abc1234)"
}

Defensive patterns

Strategy: validation

Validate before calling

const maxDesc = 1000
if job.VersionTag != nil && len(job.VersionTag.Description) > maxDesc {
    return fmt.Errorf("version tag description is %d chars; max %d", len(job.VersionTag.Description), maxDesc)
}
return nil

Try / catch

if err := job.Validate(); err != nil {
    if strings.Contains(err.Error(), "Tagged version description") {
        return ErrVersionTagTooLong
    }
    return err
}

Prevention

Use commit subject line only, not full message, for version tags
Truncate CI-generated tag descriptions to <= 999 chars
Validate tagged jobs before register in the release pipeline

When it happens

Trigger: Submitting a job with a version_tag block whose description exceeds 1000 characters.

Common situations: CI pipelines stamping job versions with full commit messages, git notes, or generated build reports as the version tag description.

Related errors

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