What causes "dynamic_user_min must be set" in hashicorp/nomad?

Set `dynamic_user_min` in the users config block (an integer >= -1); use -1 to disable the feature.

dynamic_user_min must be set

Error message

dynamic_user_min must be set

What it means

errDynamicUserMinUnset is returned by UsersConfig.Validate() when MinDynamicUser is a nil pointer. The dynamic workload users feature requires an explicit minimum UID, so an unset pointer is treated as a configuration error rather than a default. (-1 is valid and means "disabled", but nil means "not configured".)

Source

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

// Equal returns whether u and o are the same.
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

View on GitHub (pinned to 482b49bf1a)

Solutions

Set `dynamic_user_min` in the users config block (an integer >= -1); use -1 to disable the feature.
Initialize MinDynamicUser programmatically when building UsersConfig in code.
Match with errors.Is(err, errDynamicUserMinUnset) in tests to verify the missing-field case.

Example fix

// HCL before
users {
  dynamic_user_max = 1500
}

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

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Set both dynamic_user_min and dynamic_user_max together; -1 disables the feature.
Keep config templates with explicit defaults for both fields.
Cover the missing-min case in config validation tests.

When it happens

Trigger: UsersConfig constructed with MinDynamicUser left nil (e.g. only setting MaxDynamicUser in the users config block) and then passed through Validate() during agent config parsing.

Common situations: Partially filled users config in HCL where dynamic_user_min was omitted; JSON/config decode that maps missing keys to nil pointers; test fixtures that only set one bound.

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/07db31006365e4e7. Report an issue: GitHub.