What causes "dynamic_user_max must not be negative" in hashicorp/nomad?

Change dynamic_user_max to a non-negative integer or -1 to disable dynamic users.

dynamic_user_max must not be negative

Error message

dynamic_user_max must not be negative

What it means

Users config validation sentinel errDynamicUserMaxInvalid: dynamic_user_max was set to a value below -1. -1 is allowed (unbounded), but any other negative value is invalid; the range sentinel compares *u.MaxDynamicUser < -1.

Source

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

	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 {
		return errDynamicUserMaxUnset

View on GitHub (pinned to 482b49bf1a)

Solutions

Change dynamic_user_max to a non-negative integer or -1 to disable dynamic users.
Also ensure max >= min once both are valid to avoid a logically inverted range.
Match with errors.Is(err, errDynamicUserMaxInvalid) in tests.

Example fix

// before
users {
  dynamic_user_min = 1000
  dynamic_user_max = -2
}

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

Defensive patterns

Strategy: validation

Validate before calling

if u != nil && u.MaxDynamicUser != nil && *u.MaxDynamicUser < -1 {
    return fmt.Errorf("dynamic_user_max must be >= -1")
}

Try / catch

if err := u.Validate(); err != nil {
    if errors.Is(err, errDynamicUserMaxInvalid) {
        return fmt.Errorf("dynamic_user_max must be a UID or -1 to disable")
    }
    return err
}

Prevention

Only -1 may be negative; any other negative value is invalid.
Validate min <= max once both values are set.
Lint agent configs for out-of-range dynamic user bounds.

When it happens

Trigger: Setting dynamic_user_max to an integer < -1 (e.g. -2) in the users config block or UsersConfig struct, then calling Validate().

Common situations: Sign error when entering the UID range ceiling; assuming any negative value disables the feature (only -1 does); copy-paste of a negative sentinel to the wrong field.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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