{"record":{"id":"98631fbff8f7f9dd","repo":"hcengineering/platform","slug":"unknown-operator-name","errorCode":null,"errorMessage":"unknown operator: ${name}","messagePattern":"unknown operator: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"foundations/core/packages/core/src/operator.ts","lineNumber":213,"sourceCode":"/**\n * @public\n */\nexport function isOperator (o: Record<string, any>): boolean {\n  if (o === null || typeof o !== 'object') {\n    return false\n  }\n  const keys = Object.keys(o)\n  return keys.length > 0 && keys.every((key) => key.startsWith('$'))\n}\n\n/**\n * @internal\n * @param name -\n * @returns\n */\nexport function _getOperator (name: string): _OperatorFunc {\n  const operator = operators[name]\n  if (operator === undefined) throw new Error('unknown operator: ' + name)\n  return operator\n}\n","sourceCodeStart":195,"sourceCodeEnd":216,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/foundations/core/packages/core/src/operator.ts#L195-L216","documentation":"This error is thrown by the internal _getOperator lookup in the query engine when an update operator name is not present in the registered operators table. The library supports a fixed set of MongoDB-like operators ($set, $inc, $unset, $rename, etc.) and rejects anything else at query-build time. It means the query object contains a $-keyed field the engine does not recognize.","triggerScenarios":"Calling an update/find-and-modify API with an update clause whose key is not one of the registered operators, e.g. { $push: {...} } or { $mul: {...} } when only $set/$inc/$unset/$rename are implemented. Also occurs on typos like { $st: ... } and on passing user-supplied operator names straight into the update object.","commonSituations":"Porting code written against MongoDB and assuming all Mongo operators ($push, $pull, $addToSet, $bit) exist; typos in operator names; dynamic construction of update clauses from user input or config where an unsupported operator slips in; library version differences where an operator was added later.","solutions":["Check the operator name spelling and restrict updates to the operators registered in foundations/core/packages/core/src/operator.ts ($set, $inc, $unset, $rename, etc.).","Replace unsupported operators with supported equivalents (e.g. emulate $push by reading the doc, modifying the array, and issuing $set).","If the operator should exist, register it in the operators record or upgrade to a library version that supports it.","Validate dynamically built update clauses with isOperator() plus an allow-list before passing them to the API."],"exampleFix":"// before\nawait tx.update(doc, { $push: { tags: 'new' } })\n// after\nconst tags = [...(doc.tags ?? []), 'new']\nawait tx.update(doc, { $set: { tags } })","handlingStrategy":"validation","validationCode":"const SUPPORTED = ['$set', '$inc', '$unset', '$rename'] // plus operators exported by the lib\nfunction hasKnownOperators(update: Record<string, any>): boolean {\n  return Object.keys(update).every((k) => SUPPORTED.includes(k))\n}\nif (!hasKnownOperators(updateClause)) throw new Error('unsupported update operator')","typeGuard":"function isKnownOperator(o: Record<string, any>): boolean {\n  return isOperator(o) && Object.keys(o).every((k) => k in operatorsAllowList)\n}","tryCatchPattern":"try {\n  await update(doc, clause)\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('unknown operator:')) {\n    console.error('Unsupported operator in', clause, e.message)\n  } else throw e\n}","preventionTips":["Keep a typed union of allowed operator keys and type update clauses with it.","Never pass raw user input as operator keys; map user intent to known operators.","When porting from MongoDB, diff your queries against the lib's operator table first."],"tags":["query","operators","validation"],"backgroundTag":"unknown-query-operator","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}