{"record":{"id":"55bfcc7d639aab05","repo":"Automattic/mongoose","slug":"cast-to-uuid-failed-for-value-value-type-v","errorCode":null,"errorMessage":"Cast to UUID failed for value \"${value}\" (type ${valueType}) at path \"${path}\"","messagePattern":"Cast to UUID failed for value \"(.+?)\" \\(type (.+?)\\) at path \"(.+?)\"","errorType":"validation","errorClass":"CastError","httpStatus":null,"severity":"error","filePath":"lib/schema/uuid.js","lineNumber":207,"sourceCode":"SchemaUUID.prototype.cast = function(value, doc, init, prev, options) {\n  if (utils.isNonBuiltinObject(value) &&\n      SchemaType._isRef(this, value, doc, init)) {\n    return this._castRef(value, doc, init, options);\n  }\n\n  let castFn;\n  if (typeof this._castFunction === 'function') {\n    castFn = this._castFunction;\n  } else if (typeof this.constructor.cast === 'function') {\n    castFn = this.constructor.cast();\n  } else {\n    castFn = SchemaUUID.cast();\n  }\n\n  try {\n    return castFn(value);\n  } catch (error) {\n    throw new CastError(SchemaUUID.schemaName, value, this.path, error, this);\n  }\n};\n\n/*!\n * ignore\n */\n\nfunction handleSingle(val) {\n  return this.cast(val);\n}\n\n/*!\n * ignore\n */\n\nfunction handleArray(val) {\n  return val.map((m) => {\n    return this.cast(m);","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/Automattic/mongoose/blob/49cdab01366679723b487ecb754b38570f783289/lib/schema/uuid.js#L189-L225","documentation":"CastError for `Schema.Types.UUID` paths. A value is cast by constructing a BSON UUID from it, so it must be a 32-char hex string, a 36-char hyphenated UUID string, a Buffer/Uint8Array(16), or an existing BSON UUID. Any other string (garbage, wrong length, braced '{...}'), number, or object throws this error.","triggerScenarios":"`doc.uid = 'not-a-uuid'`; `doc.uid = 123`; a truncated copy-pasted UUID (35 chars); `'{' + id + '}'` braced formatting from another library.","commonSituations":"Hand-written seed/fixture files; generating ids without the uuid package; env/config truncation; mixing binary and string representations between services.","solutions":["Generate ids with `crypto.randomUUID()` / the `uuid` package, or wrap with `new mongoose.Types.UUID(value)`","Validate the format before assigning: 32 or 36 lowercase-hex chars","Fix stored values with an aggregation/update that normalizes to canonical form","If the source sends binary, keep it as Buffer instead of a string"],"exampleFix":"// before\ndoc.uid = 'abc'; // throws\n\n// after\ndoc.uid = crypto.randomUUID(); // e.g. '3f8a1c2e-9b4d-4e6a-8f2b-1c9d8e7f6a5b'","handlingStrategy":"validation","validationCode":"const UUID_RE = /^(?:[0-9a-f]{24}|[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;\nfunction assertUuidLike(v) {\n  if (v == null || v instanceof Buffer || v instanceof Uint8Array) return;\n  if (typeof v !== 'string' || !UUID_RE.test(v)) {\n    throw new TypeError(`expected UUID string (32/36 hex chars), got: ${String(v)}`);\n  }\n}","typeGuard":"const isUuidString = v => typeof v === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v);","tryCatchPattern":"try {\n  doc.uid = value;\n} catch (err) {\n  if (err instanceof mongoose.Error.CastError && err.kind === 'UUID') {\n    // reject input; regenerate id with crypto.randomUUID() where appropriate\n  } else throw err;\n}","preventionTips":["Generate UUIDs only via crypto.randomUUID()/uuid package or new mongoose.Types.UUID()","Validate UUID fields in your API schema (zod/joi .uuid()) before they reach mongoose","Normalize braced '{...}' formats from external systems before storing"],"tags":["mongoose","uuid","cast","schema","casterror"],"backgroundTag":"value-cast-failed","analyzedSha":"49cdab01366679723b487ecb754b38570f783289","analyzedAt":"2026-08-21T22:54:00.882Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}