hashicorp/nomad · error

UI description must be under 1000 characters, currently

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.

Solutions

  1. Shorten j.UI.Description to under 1000 characters
  2. Move long notes to an external doc and keep a brief summary in description
  3. Trim the value programmatically before submit (e.g. truncate to 999 chars)
  4. 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

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.

Appendix: 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)