payloadcms/payload · critical · Error

Error: cannot find Payload config. Please create a configura

Error message

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".

What it means

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).

Source

Thrown at packages/payload/src/config/find.ts:116

      dir: path.resolve(process.cwd(), 'dist'),
      fileNames: ['payload.config.js'],
    })

    if (distConfigPath) {
      return distConfigPath
    }
  } else {
    const srcConfigPath = findUpSync({
      dir: path.resolve(process.cwd(), 'src'),
      fileNames: payloadConfigFileNames,
    })

    if (srcConfigPath) {
      return srcConfigPath
    }
  }

  throw new Error(
    '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".',
  )
}

View on GitHub (pinned to 00c58b35c0)

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.

Example fix

// before: PAYLOAD_CONFIG_PATH unset, running from repo root
// after (production)
export PAYLOAD_CONFIG_PATH=/app/dist/payload.config.js
export NODE_ENV=production

Defensive patterns

Strategy: validation

Validate before calling

import fs from 'fs'
const cfg = process.env.PAYLOAD_CONFIG_PATH
  ?? './src/payload.config.ts'
if (!fs.existsSync(cfg)) {
  throw new Error(`Payload config not found at ${cfg}. Create it or set PAYLOAD_CONFIG_PATH.`)
}

Try / catch

try {
  const config = await findConfig()
} catch (err) {
  if (/cannot find Payload config/.test((err as Error).message)) {
    process.env.PAYLOAD_CONFIG_PATH = '/app/dist/payload.config.js'
    // or create the missing file
  }
  throw err
}

Prevention

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.

When it happens

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

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

Related errors

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