payloadcms/payload · error · Error

Unknown Server Function: ${fnKey}

Error message

Unknown Server Function: ${fnKey}

What it means

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.

Source

Thrown at packages/ui/src/utilities/handleServerFunctions.ts:77

      importMap,
      serverFunctions: extraServerFunctions,
    } = args

    const { cookies, locale, permissions, req } = await initReq({ configPromise, importMap })

    const augmentedArgs: DefaultServerFunctionArgs = {
      ...fnArgs,
      cookies,
      importMap,
      locale,
      permissions,
      req,
    }

    const fn = extraServerFunctions?.[fnKey] || baseServerFunctions[fnKey]

    if (!fn) {
      throw new Error(`Unknown Server Function: ${fnKey}`)
    }

    const result = await fn(augmentedArgs)

    return transformResult ? await transformResult(result) : result
  }
}

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Ensure client and server run the same Payload version and a fresh build.
2. Register custom server functions through ServerFunctionsProvider so they appear in `extraServerFunctions`.
3. Rebuild both client and server after adding or renaming a server function.
4. Check the fnKey for typos against the keys listed in `serverFunctionRegistry.ts` (`form-state`, `table-state`, `slugify`, `render-widget`, etc.).
5. If a hard reload fixes it, treat it as a stale-build issue and clear the bundler cache.

Example fix

// before: client invokes an unregistered fn
callServerFunction({ name: 'my-custom-fn', args })

// after: register it via the provider
<ServerFunctionsProvider functions={{ 'my-custom-fn': myHandler }}>

import { sharedServerFunctions } from './serverFunctionRegistry.js'

const knownKeys = new Set(Object.keys(sharedServerFunctions))
if (!knownKeys.has(fnKey)) {
  // do not dispatch; log/alert about version drift or unregistered custom fn
}

function isRegisteredServerFunction(
  fnKey: string,
  registry: Record<string, unknown>,
): boolean {
  return Object.prototype.hasOwnProperty.call(registry, fnKey)
}

try {
  await callServerFunction(args)
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Unknown Server Function')) {
    // version drift - prompt reload or surface 'update required' UI
  } else {
    throw err
  }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unauthorized, you must be logged in to make this request.
• Unauthorized
• Unauthorized

AI-assisted analysis of payloadcms/payload@00c58b35c0 (2026-08-12). Data as JSON: /api/errors/3f82e12b732bee7e. Report an issue: GitHub.