{"record":{"id":"47a4258f88fc423c","repo":"payloadcms/payload","slug":"operator-handler-handler-name-requires-the","errorCode":null,"errorMessage":"Operator handler \"${handler.name}\" requires the \"${extensionName}\" Postgres extension, which is not installed on this database. Add it to the adapter's \"extensions\" option, or install it manually with CREATE EXTENSION.","messagePattern":"Operator handler \"(.+?)\" requires the \"(.+?)\" Postgres extension, which is not installed on this database\\. Add it to the adapter's \"extensions\" option, or install it manually with CREATE EXTENSION\\.","errorType":"http","errorClass":"APIError","httpStatus":500,"severity":"error","filePath":"packages/drizzle/src/postgres/query/assertOperatorHandlerExtensionsInstalled.ts","lineNumber":37,"sourceCode":"  drizzle,\n  operatorHandlers,\n}: Args): Promise<void> => {\n  const requiredExtensionsByHandler = operatorHandlers.flatMap((handler) =>\n    (handler.requiredExtensions ?? []).map((extensionName) => ({ extensionName, handler })),\n  )\n\n  if (!requiredExtensionsByHandler.length) {\n    return\n  }\n\n  const { rows: installedExtensionRows } = await drizzle.execute<{ extname: string }>(\n    sql`SELECT extname FROM pg_extension`,\n  )\n  const installedExtensions = new Set(installedExtensionRows.map((row) => row.extname))\n\n  for (const { extensionName, handler } of requiredExtensionsByHandler) {\n    if (!installedExtensions.has(extensionName)) {\n      throw new APIError(\n        `Operator handler \"${handler.name}\" requires the \"${extensionName}\" Postgres extension, which is not installed on this database. Add it to the adapter's \"extensions\" option, or install it manually with CREATE EXTENSION.`,\n      )\n    }\n  }\n}\n","sourceCodeStart":19,"sourceCodeEnd":43,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/drizzle/src/postgres/query/assertOperatorHandlerExtensionsInstalled.ts#L19-L43","documentation":"A connection-time `APIError` from `assertOperatorHandlerExtensionsInstalled`: a registered Postgres operator handler declares a `requiredExtensions` entry (e.g. the built-in `postgres-unaccent` handler needs `unaccent`) but that extension is not present in `pg_extension`. The check runs after `createExtensions`, so declaring the extension in the adapter `extensions` option would have installed it automatically; the throw means neither declaration nor manual install happened.","triggerScenarios":"Configuring `postgresQuery.operatorHandlers` (e.g. `postgresUnaccent()`) without listing the matching extension in the adapter `extensions` option, against a database where that extension isn't pre-installed. Also when an operator handler from a plugin/custom code declares `requiredExtensions` the DB doesn't satisfy.","commonSituations":"Using accent-insensitive search (`postgresUnaccent`) on a managed Postgres without the `unaccent` extension; deploying to a fresh DB; a custom operator handler requiring `pg_trgm`/`fuzzystrmatch` without declaring it.","solutions":["Add the extension to the adapter's `extensions` option so Payload installs it on connect, e.g. `extensions: { unaccent: true }`.","Alternatively install the extension manually: `CREATE EXTENSION IF NOT EXISTS unaccent;`.","Ensure the DB role has CREATE privilege for extensions (or pre-install as superuser).","If you don't actually need the handler, remove it from `operatorHandlers`."],"exampleFix":"// before\nnew PostgresAdapter({\n  pool,\n  postgresQuery: { operatorHandlers: [postgresUnaccent()] },\n})\n// after\nnew PostgresAdapter({\n  pool,\n  extensions: { unaccent: true },\n  postgresQuery: { operatorHandlers: [postgresUnaccent()] },\n})","handlingStrategy":"validation","validationCode":"// Before connecting, ensure every handler extension is declared\nconst required = (operatorHandlers ?? [])\n  .flatMap(h => h.requiredExtensions ?? [])\nconst declared = Object.keys(adapterOptions.extensions ?? {})\nconst missing = required.filter(e => !declared.includes(e))\nif (missing.length) {\n  throw new Error(`Declare these extensions on the adapter: ${missing.join(', ')}`)\n}\nnew PostgresAdapter(adapterOptions)","typeGuard":"const handlerRequiresExtension = (h): h is { requiredExtensions: string[] } =>\n  Array.isArray(h?.requiredExtensions) && h.requiredExtensions.length > 0","tryCatchPattern":"try {\n  await payload.db.init()\n} catch (err) {\n  if (/requires the \".*\" Postgres extension/.test(String(err?.message))) {\n    payload.logger.error('Add the missing extension to the adapter extensions option or run CREATE EXTENSION.')\n  }\n  throw err\n}","preventionTips":["Whenever you register an operator handler with requiredExtensions, also add those extensions to the adapter extensions option.","Grant the DB role privileges to CREATE EXTENSION, or pre-install extensions via infrastructure.","In CI, run migrations against a DB that mirrors production's extensions."],"tags":["postgres","extensions","operator-handlers","connection","config"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}