UI description must be under 1000 characters, currently %d

Error message

UI description must be under 1000 characters, currently %d

What it means

Job.Validate: the UI block's description exceeds the 1000-character limit (MaxDescriptionCharacters). The current length is included so the overflow can be trimmed precisely.

Source

Thrown at nomad/structs/structs.go:4814

	}

	if j.Type == JobTypeSystem {
		if j.Spreads != nil {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("System jobs may not have a spread block"))
		}
	} 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

View on GitHub (pinned to 482b49bf1a)

Solutions

Shorten j.UI.Description to under 1000 characters
Move long notes to an external doc and keep a brief summary in description
Trim the value programmatically before submit (e.g. truncate to 999 chars)
Run 'nomad job validate' to catch the length violation pre-submit

Example fix

// before
ui {
  description = "<1200-char release note text>"
}
// after
ui {
  description = "Release 1.4.0; see changelog link in repo docs."
}

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Truncate generated descriptions to <= 999 characters in templating
Keep long notes in external docs, link them instead
Check description length in CI when job specs are generated

When it happens

Trigger: Submitting a job whose ui block's description string is longer than 1000 characters.

Common situations: Machine-generated job specs that paste long release notes or URLs into ui.description, template pipelines embedding commit messages or changelogs into the description.

Related errors

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