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.

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)

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

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

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