{"record":{"id":"82e64bd35352234b","repo":"Automattic/mongoose","slug":"can-t-use-conditional-with-uuid","errorCode":null,"errorMessage":"Can't use ${conditional} with UUID.","messagePattern":"Can't use (.+?) with UUID\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/schema/uuid.js","lineNumber":269,"sourceCode":"Object.defineProperty(SchemaUUID.prototype, '$conditionalHandlers', {\n  enumerable: false,\n  value: $conditionalHandlers\n});\n\n/**\n * Casts contents for queries.\n *\n * @param {string} $conditional\n * @param {any} val\n * @api private\n */\n\nSchemaUUID.prototype.castForQuery = function($conditional, val, context) {\n  let handler;\n  if ($conditional != null) {\n    handler = this.$conditionalHandlers[$conditional];\n    if (!handler)\n      throw new Error('Can\\'t use ' + $conditional + ' with UUID.');\n    return handler.call(this, val, context);\n  }\n\n  try {\n    return this.applySetters(val, context);\n  } catch (err) {\n    if (err instanceof CastError && err.path === this.path && this.$fullPath != null) {\n      err.path = this.$fullPath;\n    }\n    throw err;\n  }\n};\n\n/**\n * Returns this schema type's representation in a JSON schema.\n *\n * @param {object} [options]\n * @param {boolean} [options.useBsonType=false] If true, return a representation with `bsonType` for use with MongoDB's `$jsonSchema`.","sourceCodeStart":251,"sourceCodeEnd":287,"githubUrl":"https://github.com/Automattic/mongoose/blob/49cdab01366679723b487ecb754b38570f783289/lib/schema/uuid.js#L251-L287","documentation":"UUID paths support a limited operator set in query casting: the base handlers ($eq, $in, $ne, $nin, $all, $exists, $type) plus the $bitsAllSet/$bitsAnySet/$bitsAllClear/$bitsAnyClear bitwise operators. Any other operator — most commonly $regex or $gt/$lt — has no handler in SchemaUUID.castForQuery and throws this error at query build time.","triggerScenarios":"`Model.find({ uid: { $regex: /ff$/ } })`; `{ uid: { $gt: '0000...' } }`; copy-pasting a string filter onto a UUID path.","commonSituations":"Search-as-you-type UIs applying regex to every field; range comparisons on UUIDs; generic filter builders ignoring field types.","solutions":["Match full UUIDs with equality (`$eq`/`$in`) instead of partial matching","If you truly need regex/partial search, keep a separate string shadow field (or use $toString in an aggregation pipeline)","Remove range/geospatial operators from UUID paths"],"exampleFix":"// before\nModel.find({ uid: { $regex: /^3f8a/ } }); // throws\n\n// after\nModel.find({ uid: '3f8a1c2e-9b4d-4e6a-8f2b-1c9d8e7f6a5b' });","handlingStrategy":"validation","validationCode":"const UUID_PATH_OPS = new Set(['$eq','$in','$ne','$nin','$all','$exists','$type','$bitsAllSet','$bitsAnySet','$bitsAllClear','$bitsAnyClear']);\nfunction assertUuidOp(op) {\n  if (!UUID_PATH_OPS.has(op)) throw new Error(`operator ${op} is not supported on UUID paths; use equality or a string shadow field`);\n}","typeGuard":"const isSupportedUuidOp = op => UUID_PATH_OPS.has(op);","tryCatchPattern":"try {\n  await Model.find({ uid: { [op]: val } });\n} catch (err) {\n  if (/^Can't use \\$(\\w+) with UUID\\.$/.test(err.message)) {\n    // drop the unsupported operator or move partial matching to a string field\n  } else throw err;\n}","preventionTips":["Treat UUIDs as opaque identifiers: full-value equality only","For searchable identifiers keep a separate lowercase string field for regex/prefix search"],"tags":["mongoose","uuid","query","operators"],"backgroundTag":"unsupported-query-operator","analyzedSha":"49cdab01366679723b487ecb754b38570f783289","analyzedAt":"2026-08-21T22:54:00.882Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}