payloadcms / payloadcms/payload

payload run crashes on Node 24: loadEnvConfig of undefined in loadEnv.ts

Open Beginner friendly
#16,341 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area: core stale status: needs-triage
Dominant language
TypeScript
Stars
44.8k
Forks
4.2k
Avg merge
2d 21h
Merged PRs (30d)
53

Description

Describe the Bug

payload run <script> crashes immediately on Node.js 24 with:

TypeError: Cannot destructure property 'loadEnvConfig' of 'import_env.default' as it is undefined.
at loadedEnvFiles (payload/dist/bin/loadEnv.js:3:9)

Root cause

loadEnv.ts uses a default import from @next/env:

import nextEnvImport from '@next/env'
const { loadEnvConfig } = nextEnvImport

@next/env is a CJS-only package with no default export. Its bundle sets __esModule: true on module.exports but no .default
property. Node 24 strictly follows the __esModule flag and returns undefined for the default import. Older Node versions
(18/20) fall back to the whole module.exports object, which is why this only surfaces on Node 24.

Fix

Use a namespace import with a fallback instead of a default import:

- import nextEnvImport from '@next/env'
- const { loadEnvConfig } = nextEnvImport
+ import * as nextEnvImport from '@next/env'
+ const loadEnvConfig = nextEnvImport.loadEnvConfig ?? (nextEnvImport as any).default?.loadEnvConfig

Named imports (import { loadEnvConfig }) also fail on Node 24. The CJS bundle is not statically analyzable so Node cannot
detect its named exports. The namespace import (import * as) is the only form that works.

Environment

  • Payload: 3.83.0
  • Node: 24.15.0
  • OS: Linux (WSL2)
Link to the code that reproduces this issue

https://github.com/payloadcms/payload/blob/main/packages/payload/src/bin/loadEnv.ts

Reproduction Steps
  1. Create a Payload 3.x + Next.js project (npx create-payload-app)
  2. Create a script at src/scripts/test.ts:
import { getPayload } from 'payload'
import config from '@payload-config'

async function main() {
  const payload = await getPayload({ config })
  console.log('ok')
  await payload.destroy()
}

main()
  1. Run npx payload run src/scripts/test.ts with Node.js 24

Expected: script runs and prints ok
Actual: crashes before the script executes with TypeError: Cannot destructure property 'loadEnvConfig' of 'import_env.default'
as it is undefined

Does not reproduce on Node 18 or 20. only Node 24, which enforces stricter CJS→ESM interop rules.

Which area(s) are affected?

area: core

Environment Info
- Payload: 3.83.0
- Node.js: 24.15.0
- Next.js: 16.2.4
- OS: Linux (WSL2) / Ubuntu

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with packages/payload/src/bin/loadEnv.ts and reproduce the failure using npx payload run src/scripts/test.ts on Node.js 24. Verify the environment-loading import works with the CJS-only @next/env package, then confirm the reproduction script runs and prints ok without the destructuring error.

Written by the indexing model from the issue text.

Assessment

Tech stack
next.js, node.js, typescript
Domain
cli
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.