{"record":{"id":"78381cf21376af3c","repo":"payloadcms/payload","slug":"error-the-payload-config-is-required-to-initializ","errorCode":null,"errorMessage":"Error: the payload config is required to initialize payload.","messagePattern":"Error: the payload config is required to initialize payload\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/payload/src/index.ts","lineNumber":916,"sourceCode":"\n  /**\n   * @description Initializes Payload\n   * @param options\n   */\n  async init(options: InitOptions): Promise<Payload> {\n    if (\n      process.env.NODE_ENV !== 'production' &&\n      process.env.PAYLOAD_DISABLE_DEPENDENCY_CHECKER !== 'true' &&\n      !checkedDependencies\n    ) {\n      checkedDependencies = true\n      void checkPayloadDependencies()\n    }\n\n    this.importMap = options.importMap!\n\n    if (!options?.config) {\n      throw new Error('Error: the payload config is required to initialize payload.')\n    }\n\n    this.config = await options.config\n    this.logger = getLogger('payload', this.config.logger)\n\n    if (!this.config.secret) {\n      throw new Error('Error: missing secret key. A secret key is needed to secure Payload.')\n    }\n\n    this.encryptionKeyring = buildEncryptionKeyring([\n      this.config.secret,\n      ...(this.config.previousSecrets ?? []),\n    ])\n    this.secret = this.encryptionKeyring.active.legacyKey\n\n    this.globals = {\n      config: this.config.globals,\n    }","sourceCodeStart":898,"sourceCodeEnd":934,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/payload/src/index.ts#L898-L934","documentation":"Thrown during Payload initialization (the `Payload` class constructor/init) when `options.config` is falsy. Payload cannot build its logger, secret, or any subsystem without the resolved config object, so it refuses to boot. It is the first guard before `await options.config` is dereferenced.","triggerScenarios":"Constructing Payload and calling init() (or the internal init flow) without passing a `config` option, e.g. `payload.init({ secret, ... })` with no config, or passing config as undefined due to a bad import.","commonSituations":"A circular import or ESM/CJS resolution issue makes the config module evaluate to undefined; migrating to a bundler (Next.js, Turbopack) that tree-shakes the config import; misconfiguring the entry point so init runs before the config is loaded.","solutions":["Pass the resolved config: `payload.init({ config, secret })` or `new Payload().init({ config })`.","Check that the config import is not undefined: log `typeof config` right before init to catch bad module resolution.","If using Next.js, ensure `payload.config.ts` is the file actually imported (correct path/extension) and not shadowed."],"exampleFix":"// before\npayload.init({ secret })\n\n// after\nimport config from './payload.config'\npayload.init({ config, secret })","handlingStrategy":"validation","validationCode":"import config from './payload.config'\n\nif (!config) {\n  throw new Error('payload.config import resolved to undefined; check module resolution')\n}\n\nawait payload.init({ config, secret: process.env.PAYLOAD_SECRET })","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')","tryCatchPattern":"try {\n  await payload.init({ config, secret })\n} catch (err) {\n  if (err instanceof Error && err.message.includes('payload config is required')) {\n    // fix the config import / pass config, then retry startup\n  }\n  throw err\n}","preventionTips":["Add a startup smoke test that builds the config and asserts it is non-undefined.","Use a single canonical entry that imports config once and forwards it to init.","After bundler/Next.js upgrades, verify the config module still resolves at runtime."],"tags":["initialization","configuration","startup"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}