{"record":{"id":"3f82e12b732bee7e","repo":"payloadcms/payload","slug":"unknown-server-function-fnkey","errorCode":null,"errorMessage":"Unknown Server Function: ${fnKey}","messagePattern":"Unknown Server Function: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/ui/src/utilities/handleServerFunctions.ts","lineNumber":77,"sourceCode":"      importMap,\n      serverFunctions: extraServerFunctions,\n    } = args\n\n    const { cookies, locale, permissions, req } = await initReq({ configPromise, importMap })\n\n    const augmentedArgs: DefaultServerFunctionArgs = {\n      ...fnArgs,\n      cookies,\n      importMap,\n      locale,\n      permissions,\n      req,\n    }\n\n    const fn = extraServerFunctions?.[fnKey] || baseServerFunctions[fnKey]\n\n    if (!fn) {\n      throw new Error(`Unknown Server Function: ${fnKey}`)\n    }\n\n    const result = await fn(augmentedArgs)\n\n    return transformResult ? await transformResult(result) : result\n  }\n}\n","sourceCodeStart":59,"sourceCodeEnd":85,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/ui/src/utilities/handleServerFunctions.ts#L59-L85","documentation":"Thrown by the server-function dispatcher when the `name` (fnKey) sent from the client does not match any handler in the shared registry (`sharedServerFunctions`) or in the adapter's extra server functions. The dispatcher merges the shared set with optional adapter functions; an unknown key means the client is asking for a handler the server never registered.","triggerScenarios":"Client/server version mismatch (a newer client calling an older server), a typo or renamed function key, a custom server function that was never registered via ServerFunctionsProvider, a stale build after adding or renaming a server function, tree-shaking dropping a handler registration.","commonSituations":"Deploying a client before its server build, removing/renaming a server function without updating callsites, bundler misconfiguration that strips handler registration, dev-server cache holding an old registry.","solutions":["Ensure client and server run the same Payload version and a fresh build.","Register custom server functions through ServerFunctionsProvider so they appear in `extraServerFunctions`.","Rebuild both client and server after adding or renaming a server function.","Check the fnKey for typos against the keys listed in `serverFunctionRegistry.ts` (`form-state`, `table-state`, `slugify`, `render-widget`, etc.).","If a hard reload fixes it, treat it as a stale-build issue and clear the bundler cache."],"exampleFix":"// before: client invokes an unregistered fn\ncallServerFunction({ name: 'my-custom-fn', args })\n\n// after: register it via the provider\n<ServerFunctionsProvider functions={{ 'my-custom-fn': myHandler }}>","handlingStrategy":"validation","validationCode":"import { sharedServerFunctions } from './serverFunctionRegistry.js'\n\nconst knownKeys = new Set(Object.keys(sharedServerFunctions))\nif (!knownKeys.has(fnKey)) {\n  // do not dispatch; log/alert about version drift or unregistered custom fn\n}","typeGuard":"function isRegisteredServerFunction(\n  fnKey: string,\n  registry: Record<string, unknown>,\n): boolean {\n  return Object.prototype.hasOwnProperty.call(registry, fnKey)\n}","tryCatchPattern":"try {\n  await callServerFunction(args)\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Unknown Server Function')) {\n    // version drift - prompt reload or surface 'update required' UI\n  } else {\n    throw err\n  }\n}","preventionTips":["Lock client and server to the same Payload version.","Register every custom handler in a single ServerFunctionsProvider.","Add a build smoke test asserting the expected registry keys are present.","Hard-reload / clear the bundler cache when a newly added server function is not found."],"tags":["server-functions","rpc","version-mismatch","build"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}