{"record":{"id":"85aec98e7a4bfe28","repo":"payloadcms/payload","slug":"error-cannot-find-payload-config-please-create-a","errorCode":null,"errorMessage":"Error: cannot find Payload config. Please create a configuration file located at the root of your current working directory called \"payload.config.js\" or \"payload.config.ts\".","messagePattern":"Error: cannot find Payload config\\. Please create a configuration file located at the root of your current working directory called \"payload\\.config\\.js\" or \"payload\\.config\\.ts\"\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/payload/src/config/find.ts","lineNumber":116,"sourceCode":"      dir: path.resolve(process.cwd(), 'dist'),\n      fileNames: ['payload.config.js'],\n    })\n\n    if (distConfigPath) {\n      return distConfigPath\n    }\n  } else {\n    const srcConfigPath = findUpSync({\n      dir: path.resolve(process.cwd(), 'src'),\n      fileNames: payloadConfigFileNames,\n    })\n\n    if (srcConfigPath) {\n      return srcConfigPath\n    }\n  }\n\n  throw new Error(\n    'Error: cannot find Payload config. Please create a configuration file located at the root of your current working directory called \"payload.config.js\" or \"payload.config.ts\".',\n  )\n}\n","sourceCodeStart":98,"sourceCodeEnd":120,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/payload/src/config/find.ts#L98-L120","documentation":"Thrown by `findConfig` when no `payload.config.js`/`payload.config.ts` is located in the tsconfig paths, `PAYLOAD_CONFIG_PATH`, `src`, `dist`, or any parent directory. Payload needs a config file to boot the server, run the CLI, or seed. The search respects tsconfig `paths['@payload-config']` and differs between dev (prefers src) and production (prefers dist).","triggerScenarios":"Running `payload` CLI from a directory other than the project root; deploying to production where only `dist/` exists but `NODE_ENV` is not set to `production`; tsconfig `@payload-config` path alias pointing at a non-existent file; missing config file entirely in a fresh scaffold.","commonSituations":"Production container sets `WORKDIR /app` but runs from `/`; build outputs to `dist` yet `NODE_ENV` is unset so it searches `src` first; monorepo where the config lives in a sub-package but the CLI runs at the root; CI running migrations before building.","solutions":["Create `src/payload.config.ts` (or `payload.config.ts` at root) exporting `buildConfig({...})`.","Set `PAYLOAD_CONFIG_PATH=/app/dist/payload.config.js` (absolute) in production so the search is skipped.","Set `NODE_ENV=production` in deployments so `dist/` is searched before `src/`.","Run the CLI from the package directory that contains the config."],"exampleFix":"// before: PAYLOAD_CONFIG_PATH unset, running from repo root\n// after (production)\nexport PAYLOAD_CONFIG_PATH=/app/dist/payload.config.js\nexport NODE_ENV=production","handlingStrategy":"validation","validationCode":"import fs from 'fs'\nconst cfg = process.env.PAYLOAD_CONFIG_PATH\n  ?? './src/payload.config.ts'\nif (!fs.existsSync(cfg)) {\n  throw new Error(`Payload config not found at ${cfg}. Create it or set PAYLOAD_CONFIG_PATH.`)\n}","typeGuard":null,"tryCatchPattern":"try {\n  const config = await findConfig()\n} catch (err) {\n  if (/cannot find Payload config/.test((err as Error).message)) {\n    process.env.PAYLOAD_CONFIG_PATH = '/app/dist/payload.config.js'\n    // or create the missing file\n  }\n  throw err\n}","preventionTips":["Set `PAYLOAD_CONFIG_PATH` to an absolute path in production containers.","Set `NODE_ENV=production` so `dist/` is searched first.","Run Payload CLI commands from the package directory that owns the config.","Ensure the build emits `dist/payload.config.js` before deploying."],"tags":["config","bootstrap","cli","deployment","environment"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}