transparent proxy block has invalid ExcludeUIDs field: %w

Error message

transparent proxy block has invalid ExcludeUIDs field: %w

What it means

For each entry in transparent_proxy.exclude_uids, requireUIDisUint validates it as a uint16 decimal; failures are wrapped as 'transparent proxy block has invalid ExcludeUIDs field' and appended to the validation multi-error.

Source

Thrown at nomad/structs/connect.go:150

			e, ok := err.(*strconv.NumError)
			if !ok {
				return fmt.Errorf("invalid user ID %q: %w", uidRaw, err)
			}
			return fmt.Errorf("invalid user ID %q: %w", uidRaw, e.Err)
		}
		return nil
	}

	if tp.UID != "" {
		if err := requireUIDisUint(tp.UID); err != nil {
			mErr.Errors = append(mErr.Errors,
				fmt.Errorf("transparent proxy block has invalid UID field: %w", err))
		}
	}
	for _, uid := range tp.ExcludeUIDs {
		if err := requireUIDisUint(uid); err != nil {
			mErr.Errors = append(mErr.Errors,
				fmt.Errorf("transparent proxy block has invalid ExcludeUIDs field: %w", err))
		}
	}

	// note: ExcludeInboundPorts are validated in connect validation hook
	// because we need information from the network block

	if mErr.Len() == 1 {
		return mErr.Errors[0]
	}
	return mErr.ErrorOrNil()
}

func (tp *ConsulTransparentProxy) Equal(o *ConsulTransparentProxy) bool {
	if tp == nil || o == nil {
		return tp == o
	}
	if tp.UID != o.UID {
		return false

View on GitHub (pinned to 482b49bf1a)

Solutions

Ensure every exclude_uids entry is a numeric UID string within 0-65535
Convert usernames with id -u <user> before adding them to the list
Read the wrapped strconv error to identify which entry failed and why

Example fix

// before
transparent_proxy {
  exclude_uids = ["root", "999999"]
}
// after
transparent_proxy {
  exclude_uids = ["0", "59999"]
}

Defensive patterns

Strategy: validation

Validate before calling

for _, uid := range tp.ExcludeUIDs {
    if _, err := strconv.ParseUint(uid, 10, 16); err != nil {
        return fmt.Errorf("exclude_uids entry %q must be numeric 0-65535", uid)
    }
}

Try / catch

if err := job.Validate(); err != nil {
    if strings.Contains(err.Error(), "invalid ExcludeUIDs field") {
        return fmt.Errorf("one or more exclude_uids entries are not valid uint16 strings: %w", err)
    }
    return err
}

Prevention

Convert usernames to numeric UIDs with `id -u` before listing them
Lint exclude_uids entries against ^[0-9]{1,5}$ in CI
Keep exclude lists small and review entries for range validity

When it happens

Trigger: Validate() encounters an exclude_uids element that is not a valid unsigned 16-bit integer string (non-numeric, >65535, malformed).

Common situations: Listing usernames in exclude_uids instead of numeric IDs; copy-paste artifacts like trailing commas or spaces; out-of-range UIDs.

Related errors

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