hashicorp/nomad · error

token name too long

Error message

token name too long

What it means

A validation error produced by ACLToken.Validate. Nomad caps the human-friendly ACL token Name at maxTokenNameLength (256 characters); exceeding it appends this error to the multierror that rejects the token create/update.

Solutions

1. Shorten the token name to 256 characters or fewer
2. Move descriptive metadata into the token's other fields or external tracking
3. Validate name length client-side before submitting the token

Example fix

// before
token.Name = "ci-deployer-" + strings.Repeat("x", 300)
// after
name := "ci-deployer-" + strings.Repeat("x", 300)
token.Name = name[:256] // or a shorter, meaningful name

if len(token.Name) > 256 {
    return fmt.Errorf("token name must be at most 256 characters, got %d", len(token.Name))
}

func validTokenName(name string) bool { return len(name) > 0 && len(name) <= 256 }

if err := token.Validate(minTTL, maxTTL, existing); err != nil {
    if strings.Contains(err.Error(), "token name too long") {
        token.Name = truncate(token.Name, 256)
        err = token.Validate(minTTL, maxTTL, existing)
    }
}

When it happens

Trigger: Calling ACL Upsert (token create or update) with an ACLToken whose Name exceeds 256 characters.

Common situations: Automation generating token names from long labels, UUID+description concatenations, or templated names that exceed the 256-char limit.

Related errors

• cannot toggle global mode
• cannot update expiration TTL
• client token missing policies or roles
• expiration time cannot be before create time
• management token cannot be associated with policies or roles

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

Appendix: source

Thrown at nomad/structs/acl.go:762

	// If both IDs are already set but no creation time was provided, the token
	// is being uploaded and the createTime should be set.
	if a.CreateTime.IsZero() {
		a.CreateTime = time.Now().UTC()

		if a.ExpirationTime == nil && a.ExpirationTTL != 0 {
			a.ExpirationTime = new(a.CreateTime.Add(a.ExpirationTTL))
		}
	}
}

// Validate is used to check a token for reasonableness
func (a *ACLToken) Validate(minTTL, maxTTL time.Duration, existing *ACLToken) error {
	var mErr multierror.Error

	// The human friendly name of an ACL token cannot exceed 256 characters.
	if len(a.Name) > maxTokenNameLength {
		mErr.Errors = append(mErr.Errors, errors.New("token name too long"))
	}

	// The type of an ACL token must be set. An ACL token of type client must
	// have associated policies or roles, whereas a management token cannot be
	// associated with policies.
	switch a.Type {
	case ACLClientToken:
		if len(a.Policies) == 0 && len(a.Roles) == 0 {
			mErr.Errors = append(mErr.Errors, errors.New("client token missing policies or roles"))
		}
	case ACLManagementToken:
		if len(a.Policies) != 0 || len(a.Roles) != 0 {
			mErr.Errors = append(mErr.Errors, errors.New("management token cannot be associated with policies or roles"))
		}
	default:
		mErr.Errors = append(mErr.Errors, errors.New("token type must be client or management"))
	}

View on GitHub (pinned to 482b49bf1a)