What causes "description longer than %d" in hashicorp/nomad?

Shorten the description to at most maxPolicyDescriptionLength characters and resubmit.

description longer than %d

Error message

description longer than %d

What it means

ACLPolicy.Validate enforces a maximum length on the policy Description field (maxPolicyDescriptionLength) and appends 'description longer than %d' when exceeded. Descriptions are stored metadata displayed in listings, so Nomad caps them to keep API responses and state store entries compact.

Source

Thrown at nomad/structs/acl.go:379

		JobACL:      a.JobACL,
		Hash:        a.Hash,
		CreateIndex: a.CreateIndex,
		ModifyIndex: a.ModifyIndex,
	}
}

func (a *ACLPolicy) Validate() error {
	var mErr multierror.Error
	if !ValidPolicyName.MatchString(a.Name) {
		err := fmt.Errorf("invalid name '%s'", a.Name)
		mErr.Errors = append(mErr.Errors, err)
	}
	if _, err := acl.Parse(a.Rules, acl.PolicyParseStrict); err != nil {
		err = fmt.Errorf("failed to parse rules: %v", err)
		mErr.Errors = append(mErr.Errors, err)
	}
	if len(a.Description) > maxPolicyDescriptionLength {
		err := fmt.Errorf("description longer than %d", maxPolicyDescriptionLength)
		mErr.Errors = append(mErr.Errors, err)
	}
	if a.JobACL != nil {
		if a.JobACL.JobID != "" && a.JobACL.Namespace == "" {
			err := fmt.Errorf("namespace must be set to set job ID")
			mErr.Errors = append(mErr.Errors, err)
		}
		if a.JobACL.Group != "" && a.JobACL.JobID == "" {
			err := fmt.Errorf("job ID must be set to set group")
			mErr.Errors = append(mErr.Errors, err)
		}
		if a.JobACL.Task != "" && a.JobACL.Group == "" {
			err := fmt.Errorf("group must be set to set task")
			mErr.Errors = append(mErr.Errors, err)
		}
	}

	return mErr.ErrorOrNil()

View on GitHub (pinned to 482b49bf1a)

Solutions

Shorten the description to at most maxPolicyDescriptionLength characters and resubmit.
Move long documentation into version control next to the policy HCL instead of the description field.
If scripted, truncate programmatically (e.g. cut to the limit) before calling the API.
Check the constant maxPolicyDescriptionLength in structs/acl.go for the exact current limit.

Example fix

// before
policy.Description = veryLongParagraph
// after
const maxPolicyDescriptionLength = 256
if len(veryLongParagraph) > maxPolicyDescriptionLength {
    veryLongParagraph = veryLongParagraph[:maxPolicyDescriptionLength]
}
policy.Description = veryLongParagraph

Defensive patterns

Strategy: validation

Validate before calling

const maxPolicyDescriptionLength = 256
func validateDescription(desc string) error {
    if len(desc) > maxPolicyDescriptionLength {
        return fmt.Errorf("description is %d bytes, max %d", len(desc), maxPolicyDescriptionLength)
    }
    return nil
}

Try / catch

if err := policy.Validate(); err != nil {
    if strings.Contains(err.Error(), "description longer than") {
        policy.Description = truncate(policy.Description, maxPolicyDescriptionLength)
    }
    return policy.Validate()
}

Prevention

Truncate descriptions at write time in tooling.
Keep long documentation in the policy HCL repo, not the Description field.
Note the limit counts bytes, not runes, for non-ASCII text.
Check maxPolicyDescriptionLength in structs/acl.go for the current value.

When it happens

Trigger: Submitting an ACL policy whose Description string exceeds maxPolicyDescriptionLength bytes — typically via `nomad acl policy apply -description ...` or the ACL policy API.

Common situations: Pasting a long explanatory paragraph or entire README note into the description field; scripted provisioning copying a commit message into the description; migrations from other systems (e.g. Consul policies) with longer description limits.

Related errors

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