{"record":{"id":"72b7599bbf90424e","repo":"payloadcms/payload","slug":"operator-handler-handler-name-threw-while-tra","errorCode":null,"errorMessage":"Operator handler \"${handler.name}\" threw while transforming operands for the \"${resolvedOperator}\" operator at path \"${path}\".","messagePattern":"Operator handler \"(.+?)\" threw while transforming operands for the \"(.+?)\" operator at path \"(.+?)\"\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/drizzle/src/queries/buildOperatorConstraint.ts","lineNumber":76,"sourceCode":"  const context: DrizzleOperatorHandlerContext = {\n    adapter,\n    column: args.column,\n    field,\n    locale,\n    originalOperator,\n    path,\n    resolvedOperator,\n    storage: 'column',\n    value: args.value,\n  }\n\n  for (const handler of matchingHandlers.filter(isTransformHandler)) {\n    let result: { column: Column | SQL; value: unknown }\n\n    try {\n      result = handler.transformOperands({ ...context })\n    } catch (error) {\n      throw new Error(\n        `Operator handler \"${handler.name}\" threw while transforming operands for the \"${resolvedOperator}\" operator at path \"${path}\".`,\n        { cause: error },\n      )\n    }\n\n    if (!result || typeof result !== 'object' || !('column' in result) || !('value' in result)) {\n      throw new APIError(\n        `Operator handler \"${handler.name}\" returned an invalid operand transform for the \"${resolvedOperator}\" operator at path \"${path}\". Expected an object with \"column\" and \"value\" properties.`,\n      )\n    }\n\n    context.column = result.column\n    context.value = result.value\n  }\n\n  const replacementHandler = matchingHandlers.find(isReplacementHandler)\n\n  if (replacementHandler) {","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/drizzle/src/queries/buildOperatorConstraint.ts#L58-L94","documentation":"Internal error from `buildOperatorConstraint`: a registered operator handler's `transformOperands` callback threw an exception while rewriting the column/value for a query at a given path/operator. The wrapper catches the underlying error and re-throws with context (handler name, resolved operator, path) and preserves the original via `cause`. It indicates a bug or unsupported input inside a custom/built-in operand-transform handler, not in your query itself.","triggerScenarios":"A query reaches a field/operator combination matched by a `transformOperands` handler (e.g. `postgresUnaccent` on a `contains` text field), and that handler throws — for example because of an unexpected column type or a null/undefined operand value.","commonSituations":"A custom operator handler that doesn't handle null/undefined values; an accent/transform handler applied to a column type it wasn't written for; a handler reading a property that is missing for a particular field shape.","solutions":["Inspect the `cause` of the thrown error for the handler's original exception — that is the real fault.","Harden the offending handler's `transformOperands` to handle null/undefined and unexpected column types (return `{ column, value }` unchanged when inapplicable).","Restrict the handler with `fieldTypes`/`operators` so it only matches cases it supports.","If the handler is built-in (e.g. unaccent), report the field shape that triggers it as a bug."],"exampleFix":"// custom handler before\ntransformOperands: ({ column, value }) => {\n  return { column: sql`unaccent(${column})`, value: sql`unaccent(${value})` }\n}\n// after: guard against null/undefined operands\ntransformOperands: ({ column, value }) => {\n  if (value === null || value === undefined) return { column, value }\n  return { column: sql`unaccent(${column})`, value: sql`unaccent(${value})` }\n}","handlingStrategy":"try-catch","validationCode":"// Validate handler robustness at registration time\nfor (const h of operatorHandlers ?? []) {\n  if (typeof h.transformOperands === 'function') {\n    // sanity-check it handles null gracefully\n    const r = h.transformOperands({ column: {} as any, value: null } as any)\n    if (!r || typeof r !== 'object' || !('column' in r) || !('value' in r)) {\n      throw new Error(`Handler ${h.name} must tolerate null value`) \n    }\n  }\n}","typeGuard":"null","tryCatchPattern":"try {\n  await payload.find({ collection, where })\n} catch (err) {\n  const cause = (err?.cause ?? err)\n  if (/threw while transforming operands/.test(String(err?.message))) {\n    payload.logger.error({ msg: 'Operator handler fault', cause })\n  }\n  throw err\n}","preventionTips":["Unit-test custom transformOperands handlers with null/undefined and unexpected column types.","Have handlers return { column, value } unchanged for inputs they don't transform.","Restrict handlers with fieldTypes/operators to limit the cases they receive."],"tags":["query","operator-handlers","internal","custom-handler"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}