hashicorp/nomad · error

transparent proxy block has invalid UID field: %w

Error message

transparent proxy block has invalid UID field: %w

What it means

If requireUIDisUint rejects the transparent_proxy block's uid, Validate collects 'transparent proxy block has invalid UID field' into the multi-error. It's the outer wrapper that points at the specific field, with the strconv reason nested via %w.

Source

Thrown at nomad/structs/connect.go:144

		}
	}

	requireUIDisUint := func(uidRaw string) error {
		_, err := strconv.ParseUint(uidRaw, 10, 16)
		if err != nil {
			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()
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Replace the uid value with a numeric 0-65535 string
2. If using templating, ensure the variable renders to a number before submission
3. Read the nested %w error to see the exact strconv failure

Example fix

// before
transparent_proxy {
  uid = "{{ taskUser }}"
}
// after
transparent_proxy {
  uid = "59999"
}

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

if err := job.Validate(); err != nil {
    if strings.Contains(err.Error(), "invalid UID field") {
        return fmt.Errorf("fix transparent_proxy.uid to a numeric UID: %w", err)
    }
    return err
}

When it happens

Trigger: Job/consul connect validation runs with transparent_proxy.uid set to a value that fails ParseUint(_, 10, 16), e.g. non-numeric or out-of-range strings.

Common situations: Authoring jobspecs by hand with a username instead of a numeric UID; template variables left unrendered (e.g. '{{ user }}') in the uid field.

Related errors

• transparent proxy block has invalid ExcludeUIDs field: %w
• Consul Connect transparent proxy cannot be used with network
• Consul Connect transparent proxy port %q must be numeric or
• Consul Connect transparent proxy requires there is only one
• could not parse transparent proxy excluded outbound CIDR as

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