nodejs/node · error · Error

${fieldName} must be a valid UUID

Error message

${fieldName} must be a valid UUID

What it means

validateUUID throws when a value does not match the canonical 8-4-4-4-12 hexadecimal UUID format (case-insensitive, any RFC-4122 version). It is a guard used to reject malformed identifiers before they reach npm registry/profile API endpoints. The thrown message interpolates the supplied fieldName so the caller knows which field failed.

Source

Thrown at deps/npm/lib/utils/validate-uuid.js:6

// UUID validation regex
const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i

const validateUUID = (value, fieldName) => {
  if (!UUID_REGEX.test(value)) {
    throw new Error(`${fieldName} must be a valid UUID`)
  }
}

module.exports = { UUID_REGEX, validateUUID }

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Pass the correct UUID value — fetch it from the API response field that actually contains the id (usually '*.id' or '*.org_id'), not the human-readable name.
2. Trim whitespace/newlines from the value before validating: value.trim().
3. Normalize to lowercase before calling: UUIDs are case-insensitive but canonical form is lowercase.
4. If you generate the id, produce it with crypto.randomUUID().

Example fix

// before
validateUUID(team.slug, 'teamId')  // 'design-team' fails
// after
validateUUID(team.id, 'teamId')     // '00000000-0000-4000-8000-000000000000' passes

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
function isValidUUID(v) { return typeof v === 'string' && UUID_RE.test(v) }
if (!isValidUUID(id)) throw new TypeError(`expected UUID, got: ${id}`)

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
function isUUID(v): v is string {
  return typeof v === 'string' && UUID_RE.test(v.trim())
}

try {
  validateUUID(id, 'teamId')
} catch (err) {
  throw new Error(`Refusing API call: teamId is not a UUID (${id}). Fetch the id from the API, not the slug.`)
}

When it happens

Trigger: Calling a function that internally calls validateUUID(value, fieldName) with a value that is not a UUID — e.g. a package name, slug, numeric id, truncated UUID, or a string with uppercase/non-hex characters in wrong positions.

Common situations: Passing a slug/name where an entity UUID is expected (e.g. team id, token id, org id); copy-paste truncation; mapping the wrong API response field to the id argument; storing the UUID with surrounding whitespace.

Related errors

• Invalid package, must have name and version
• The programmatic API was removed in npm v8.0.0
• `${baseKey}` is not a valid npm option
• ${argv[2]} not recognized
• First argument `orgname` is required.

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/5ed562e0c463f8fd. Report an issue: GitHub.