{"record":{"id":"5ed562e0c463f8fd","repo":"nodejs/node","slug":"fieldname-must-be-a-valid-uuid","errorCode":null,"errorMessage":"${fieldName} must be a valid UUID","messagePattern":"(.+?) must be a valid UUID","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"deps/npm/lib/utils/validate-uuid.js","lineNumber":6,"sourceCode":"// UUID validation regex\nconst UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i\n\nconst validateUUID = (value, fieldName) => {\n  if (!UUID_REGEX.test(value)) {\n    throw new Error(`${fieldName} must be a valid UUID`)\n  }\n}\n\nmodule.exports = { UUID_REGEX, validateUUID }\n","sourceCodeStart":1,"sourceCodeEnd":11,"githubUrl":"https://github.com/nodejs/node/blob/1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e/deps/npm/lib/utils/validate-uuid.js#L1-L11","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Trim whitespace/newlines from the value before validating: value.trim().","Normalize to lowercase before calling: UUIDs are case-insensitive but canonical form is lowercase.","If you generate the id, produce it with crypto.randomUUID()."],"exampleFix":"// before\nvalidateUUID(team.slug, 'teamId')  // 'design-team' fails\n// after\nvalidateUUID(team.id, 'teamId')     // '00000000-0000-4000-8000-000000000000' passes","handlingStrategy":"validation","validationCode":"const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i\nfunction isValidUUID(v) { return typeof v === 'string' && UUID_RE.test(v) }\nif (!isValidUUID(id)) throw new TypeError(`expected UUID, got: ${id}`)","typeGuard":"const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i\nfunction isUUID(v): v is string {\n  return typeof v === 'string' && UUID_RE.test(v.trim())\n}","tryCatchPattern":"try {\n  validateUUID(id, 'teamId')\n} catch (err) {\n  throw new Error(`Refusing API call: teamId is not a UUID (${id}). Fetch the id from the API, not the slug.`)\n}","preventionTips":["Always source ids from API response '*.id' fields, never from slugs/names.","Trim and lowercase UUIDs before use.","Generate ids with crypto.randomUUID().","Add a TypeScript branded type (type Uuid = string & { __brand: 'uuid' }) to prevent passing arbitrary strings."],"tags":["npm","validation","uuid","registry-api","input-validation"],"backgroundTag":null,"analyzedSha":"1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e","analyzedAt":"2026-08-13T00:53:24.642Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}