{"record":{"id":"1aad5c6e861a4dc3","repo":"colinhacks/zod","slug":"invalid-uuid-version-def-version","errorCode":null,"errorMessage":"Invalid UUID version: \"${def.version}\"","messagePattern":"Invalid UUID version: \"(.+?)\"","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/zod/src/v4/core/schemas.ts","lineNumber":443,"sourceCode":"\nexport interface $ZodUUID extends $ZodType {\n  _zod: $ZodUUIDInternals;\n}\n\nexport const $ZodUUID: core.$constructor<$ZodUUID> = /*@__PURE__*/ core.$constructor(\"$ZodUUID\", (inst, def): void => {\n  if (def.version) {\n    const versionMap: Record<string, number> = {\n      v1: 1,\n      v2: 2,\n      v3: 3,\n      v4: 4,\n      v5: 5,\n      v6: 6,\n      v7: 7,\n      v8: 8,\n    };\n    const v = versionMap[def.version];\n    if (v === undefined) throw new Error(`Invalid UUID version: \"${def.version}\"`);\n    def.pattern ??= regexes.uuid(v);\n  } else def.pattern ??= regexes.uuid();\n  $ZodStringFormat.init(inst, def);\n});\n\n//////////////////////////////   ZodEmail   //////////////////////////////\n\nexport interface $ZodEmailDef extends $ZodStringFormatDef<\"email\"> {}\nexport interface $ZodEmailInternals extends $ZodStringFormatInternals<\"email\"> {}\nexport interface $ZodEmail extends $ZodType {\n  _zod: $ZodEmailInternals;\n}\n\nexport const $ZodEmail: core.$constructor<$ZodEmail> = /*@__PURE__*/ core.$constructor(\n  \"$ZodEmail\",\n  (inst, def): void => {\n    def.pattern ??= regexes.email;\n    $ZodStringFormat.init(inst, def);","sourceCodeStart":425,"sourceCodeEnd":461,"githubUrl":"https://github.com/colinhacks/zod/blob/2d90846af918af9602e088812d63a035d47cdbe4/packages/zod/src/v4/core/schemas.ts#L425-L461","documentation":"Thrown by the $ZodUUID constructor when def.version is set to a value not present in its internal versionMap. The map only accepts the string keys \"v1\" through \"v8\" (mapped to integers 1-8), so any other string (e.g. \"v9\", \"v10\", \"uuid\", \"4\") is rejected at schema-construction time. The version is used to select the corresponding UUID regex from regexes.uuid(v).","triggerScenarios":"Calling z.uuid({ version: \"v9\" }), z.uuid({ version: \"9\" }), z.uuid({ version: \"uuid\" }), or constructing $ZodUUID with a def.version outside the v1-v8 set. Any non-empty version string that isn't exactly \"v1\"..\"v8\" triggers it; omitting version (or passing undefined) skips the check entirely and falls back to the generic UUID regex.","commonSituations":"Developers assume the version takes a bare number (\"4\") instead of the \"v4\" prefix; copying version strings from docs of other libraries; auto-generating UUID config from user input without validation; trying to use newer UUID variants (v6/v7/v8 were added later — older zod versions only supported v1-v5).","solutions":["Use one of the supported version strings: \"v1\", \"v2\", \"v3\", \"v4\", \"v5\", \"v6\", \"v7\", or \"v8\".","If you do not need a specific version, omit the version option entirely to accept any UUID format.","If your zod version predates v6/v7/v8 support, upgrade zod to a release that includes them.","Validate or sanitize user-supplied version strings against the allowed set before passing them to z.uuid()."],"exampleFix":"// before\nconst Id = z.uuid({ version: \"v9\" });\n// after\nconst Id = z.uuid({ version: \"v7\" });\n// or accept any version\nconst Id = z.uuid();","handlingStrategy":"validation","validationCode":"const ALLOWED = new Set([\"v1\",\"v2\",\"v3\",\"v4\",\"v5\",\"v6\",\"v7\",\"v8\"]);\nfunction makeUuid(version?: string) {\n  if (version !== undefined && !ALLOWED.has(version)) {\n    throw new Error(`Unsupported UUID version: ${version}. Allowed: ${[...ALLOWED].join(\", \")}`);\n  }\n  return version ? z.uuid({ version }) : z.uuid();\n}","typeGuard":"function isValidUuidVersion(v: unknown): v is `v${1|2|3|4|5|6|7|8}` {\n  return typeof v === \"string\" && /^v[1-8]$/.test(v);\n}","tryCatchPattern":"try {\n  const Id = makeUuid(config.version);\n} catch (e) {\n  // surface a config-level error to the user, with the allowed list\n  throw new Error(`Bad config.version: ${(e as Error).message}`);\n}","preventionTips":["Treat UUID version as an enum in your config schema, not a free string.","Default to omitting version when you don't need a specific variant.","Document the v1-v8 allow-list wherever the option is exposed."],"tags":["uuid","schema-construction","validation","regex"],"backgroundTag":null,"analyzedSha":"2d90846af918af9602e088812d63a035d47cdbe4","analyzedAt":"2026-08-11T01:21:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-22T11:17:16.035Z"}