payloadcms/payload · critical · Error

Error: the payload config is required for getPayload to work

Error message

Error: the payload config is required for getPayload to work.

What it means

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.

Source

Thrown at packages/payload/src/index.ts:1306

     * passed to `registerDevReloadStrategy` and over the default Next.js HMR
     * WebSocket listener. The strategy's `connect` function receives a callback to
     * trigger config reload.
     *
     * Pass a stable reference: a strategy is reconnected whenever its identity
     * changes, so a new object literal on every call reconnects on every call.
     */
    devReloadStrategy?: DevReloadStrategy
    /**
     * A unique key to identify the payload instance. You can pass your own key if you want to cache this payload instance separately.
     * This is useful if you pass a different payload config for each instance.
     *
     * @default 'default'
     */
    key?: string
  } & InitOptions,
): Promise<Payload> => {
  if (!options?.config) {
    throw new Error('Error: the payload config is required for getPayload to work.')
  }

  let alreadyCachedSameConfig = false

  let cached = _cached.get(options.key ?? 'default')
  if (!cached) {
    cached = {
      devReloadCleanup: null,
      devReloadStrategy: null,
      initializedCrons: Boolean(options.cron),
      payload: null,
      promise: null,
      reload: false,
    }
    _cached.set(options.key ?? 'default', cached)
  } else {
    alreadyCachedSameConfig = true
  }

View on GitHub (pinned to 00c58b35c0)

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.

Example fix

// before
const payload = await getPayload({})

// after
import config from '../payload.config'
const payload = await getPayload({ config })

Defensive patterns

Strategy: validation

Validate before calling

import config from './payload.config'

if (!config) throw new Error('config import is undefined')
const payload = await getPayload({ config })

Type guard

import type { Config } from 'payload'

function isConfig(value: unknown): value is Config {
  return Boolean(value && typeof value === 'object' && 'collections' in (value as object))
}

if (!isConfig(config)) throw new Error('Invalid payload config for getPayload')

Try / catch

try {
  const payload = await getPayload({ config })
} catch (err) {
  if (err instanceof Error && err.message.includes('payload config is required for getPayload')) {
    // re-import / fix the config path, then retry
  }
  throw err
}

Prevention

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.

When it happens

Trigger: Calling `getPayload({})` or `getPayload()` with no config, or `getPayload({ config: undefined })` because of a broken import of the config module.

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

Related errors

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