hashicorp/nomad · error

dynamic_user_max must be set

Error message

dynamic_user_max must be set

What it means

errDynamicUserMaxUnset is returned by UsersConfig.Validate() when MaxDynamicUser is a nil pointer. Like the min bound, the maximum dynamic UID must be explicitly configured; a nil pointer means the field was never set and validation fails. -1 is allowed and disables the feature.

Source

Thrown at nomad/structs/config/users.go:67

func (u *UsersConfig) Equal(o *UsersConfig) bool {
	if u == nil || o == nil {
		return u == o
	}
	switch {
	case !pointer.Eq(u.MinDynamicUser, o.MinDynamicUser):
		return false
	case !pointer.Eq(u.MaxDynamicUser, o.MaxDynamicUser):
		return false
	default:
		return true
	}
}

var (
	errUsersUnset            = errors.New("users must not be nil")
	errDynamicUserMinUnset   = errors.New("dynamic_user_min must be set")
	errDynamicUserMinInvalid = errors.New("dynamic_user_min must not be negative")
	errDynamicUserMaxUnset   = errors.New("dynamic_user_max must be set")
	errDynamicUserMaxInvalid = errors.New("dynamic_user_max must not be negative")
)

// Validate whether UsersConfig is valid.
//
// Note that -1 is a valid value for min/max dynamic users, as this is used
// to indicate the dynamic workload users feature should be disabled.
func (u *UsersConfig) Validate() error {
	if u == nil {
		return errUsersUnset
	}
	if u.MinDynamicUser == nil {
		return errDynamicUserMinUnset
	}
	if *u.MinDynamicUser < -1 {
		return errDynamicUserMinInvalid
	}
	if u.MaxDynamicUser == nil {

View on GitHub (pinned to 482b49bf1a)

Solutions

  1. Add `dynamic_user_max` to the users config block (integer >= -1; -1 disables the feature).
  2. Set MaxDynamicUser when constructing the struct programmatically.
  3. Use errors.Is(err, errDynamicUserMaxUnset) in tests to assert this specific failure.

Example fix

// HCL before
users {
  dynamic_user_min = 1000
}

// HCL after
users {
  dynamic_user_min = 1000
  dynamic_user_max = 1500
}
Defensive patterns

Strategy: validation

Validate before calling

if u != nil && u.MaxDynamicUser == nil {
    return fmt.Errorf("dynamic_user_max must be set (use -1 to disable)")
}

Try / catch

if err := u.Validate(); err != nil {
    if errors.Is(err, errDynamicUserMaxUnset) {
        return fmt.Errorf("set dynamic_user_max in the users config block")
    }
    return err
}

Prevention

When it happens

Trigger: UsersConfig built with only MinDynamicUser set (MaxDynamicUser nil) — e.g. an HCL users block with dynamic_user_min but no dynamic_user_max — passed through Validate().

Common situations: Partial users stanza in agent config; code constructing UsersConfig and forgetting the max bound; JSON decode of a config missing the key yielding nil.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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