{"record":{"id":"f830035fc58cb6eb","repo":"payloadcms/payload","slug":"error-the-payload-config-is-required-for-getpaylo","errorCode":null,"errorMessage":"Error: the payload config is required for getPayload to work.","messagePattern":"Error: the payload config is required for getPayload to work\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/payload/src/index.ts","lineNumber":1306,"sourceCode":"     * passed to `registerDevReloadStrategy` and over the default Next.js HMR\n     * WebSocket listener. The strategy's `connect` function receives a callback to\n     * trigger config reload.\n     *\n     * Pass a stable reference: a strategy is reconnected whenever its identity\n     * changes, so a new object literal on every call reconnects on every call.\n     */\n    devReloadStrategy?: DevReloadStrategy\n    /**\n     * A unique key to identify the payload instance. You can pass your own key if you want to cache this payload instance separately.\n     * This is useful if you pass a different payload config for each instance.\n     *\n     * @default 'default'\n     */\n    key?: string\n  } & InitOptions,\n): Promise<Payload> => {\n  if (!options?.config) {\n    throw new Error('Error: the payload config is required for getPayload to work.')\n  }\n\n  let alreadyCachedSameConfig = false\n\n  let cached = _cached.get(options.key ?? 'default')\n  if (!cached) {\n    cached = {\n      devReloadCleanup: null,\n      devReloadStrategy: null,\n      initializedCrons: Boolean(options.cron),\n      payload: null,\n      promise: null,\n      reload: false,\n    }\n    _cached.set(options.key ?? 'default', cached)\n  } else {\n    alreadyCachedSameConfig = true\n  }","sourceCodeStart":1288,"sourceCodeEnd":1324,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/payload/src/index.ts#L1288-L1324","documentation":"Thrown by the `getPayload` Local API factory when `options.config` is not supplied. Unlike the server init path, getPayload builds an in-process instance and must have the config to construct and cache the Payload object (it caches by key, default 'default'). Without config it cannot proceed.","triggerScenarios":"Calling `getPayload({})` or `getPayload()` with no config, or `getPayload({ config: undefined })` because of a broken import of the config module.","commonSituations":"Using the Local API in scripts, server components, or tests and forgetting to pass config; an ESM default-vs-named import mistake returning undefined for config; switching from `payload.init` (server) to `getPayload` (local) and not forwarding the config.","solutions":["Pass the config: `const payload = await getPayload({ config })`.","Verify the config import resolves: `if (!config) throw new Error('config import broken')` before getPayload.","If you need the already-initialized server instance instead, use the global `payload` rather than getPayload."],"exampleFix":"// before\nconst payload = await getPayload({})\n\n// after\nimport config from '../payload.config'\nconst payload = await getPayload({ config })","handlingStrategy":"validation","validationCode":"import config from './payload.config'\n\nif (!config) throw new Error('config import is undefined')\nconst payload = await getPayload({ config })","typeGuard":"import type { Config } from 'payload'\n\nfunction isConfig(value: unknown): value is Config {\n  return Boolean(value && typeof value === 'object' && 'collections' in (value as object))\n}\n\nif (!isConfig(config)) throw new Error('Invalid payload config for getPayload')","tryCatchPattern":"try {\n  const payload = await getPayload({ config })\n} catch (err) {\n  if (err instanceof Error && err.message.includes('payload config is required for getPayload')) {\n    // re-import / fix the config path, then retry\n  }\n  throw err\n}","preventionTips":["Create one helper (`getLocalPayload()`) that imports config and calls getPayload, reused everywhere.","Verify the config import resolves under your bundler (especially Next.js/ESM).","Pass the already-running server `payload` instance instead of getPayload where possible."],"tags":["local-api","configuration","startup"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}