PM2 says the ecosystem file is malformated and refuses to start
[PM2][ERROR] File ecosystem.config.js malformatedShort answer
PM2 prints 'malformated' whenever loading the config file throws. The word is only a wrapper: the real error is printed on the lines right below it. Read that first. It is usually a JavaScript error inside the file, ES module syntax in a CommonJS loader, or JS code saved under a .json or .yml name.
Fix it fast
1Find out which cause you have
Load the file with plain Node.js. It throws the same error PM2 hides behind the word malformated, with a line number.
node -e "console.log(require('./ecosystem.config.js'))"2Match what you see, then jump to its fix
- 1
The stack trace under the malformated line points at a line of your ecosystem file, for example a ReferenceError or a missing module.A JavaScript error inside the config fileFix - 2
SyntaxError: Unexpected token 'export', or ERR_REQUIRE_ASYNC_MODULE, right under the malformated lineThe file uses ES module syntax or top-level awaitFix - 3
The file is called ecosystem.json, ecosystem.yml or similar, but it contains module.exports or require()JavaScript saved in a .json or .yml fileFix
- 1
What does the error look like?
[PM2][ERROR] File ecosystem.config.js malformatedError [ERR_REQUIRE_ASYNC_MODULE]SyntaxError: Unexpected token 'export'
Cause 1 of 3
A JavaScript error inside the config file
1Check
PM2 reads a .config.js file with require(). If any line throws while loading, PM2 prints the malformated message and then the thrown error. Run the one-line check from the first step and read the top of the stack trace.
node -e "require('./ecosystem.config.js')"2Fix
Fix the line the stack trace names: a typo, a require() of a package that is not installed in this folder, or code that reads a file that does not exist. The file must end with module.exports = { apps: [ ... ] }.
module.exports = {
apps: [
{
name: "my-app",
script: "./server.js",
},
],
};3Verify
The check from the first step prints the object instead of an error, and PM2 starts the app.
node -e "console.log(require('./ecosystem.config.js'))"
pm2 start ecosystem.config.jsConfirmed by github.com
Cause 2 of 3
The file uses ES module syntax or top-level await
1Check
PM2 loads .js and .cjs config files with require(). Node.js can require() an ES module only when it has no top-level await, and only in versions that support it (22.12 and later). Check for export, import or await at the top level of the file.
node --version
grep -n -E "^(export|import)|^await " ecosystem.config.js2Fix
Write the config as CommonJS and give it the extension .config.cjs, which PM2 recognises. Replace export default with module.exports, and move any await out of the file.
# rename, then edit the file to use module.exports
mv ecosystem.config.js ecosystem.config.cjs
pm2 start ecosystem.config.cjs3Verify
pm2 start accepts the file and the process shows as online.
pm2 statusConfirmed by nodejs.org
Cause 3 of 3
JavaScript saved in a .json or .yml file
1Check
PM2 decides how to parse a file from its name. A .json file is evaluated as one object literal, and a .yml or .yaml file is parsed as YAML. Only names ending in .config.js, .config.cjs or .config.mjs are loaded as code.
ls ecosystem.* && head -n 3 ecosystem.*2Fix
Match the name to the content: JavaScript goes in ecosystem.config.js (or .config.cjs); a file that really is JSON or YAML keeps its extension and must contain only data.
mv ecosystem.json ecosystem.config.js
pm2 start ecosystem.config.js3Verify
PM2 prints a table with your app instead of the malformated line.
pm2 statusConfirmed by github.com
How do I stop it coming back?
- Run node -e "require('./ecosystem.config.js')" in CI or before every deploy, so a broken file is caught before PM2 sees it.
- Keep the ecosystem file CommonJS even when the app itself uses ES modules, and name it .config.cjs when package.json has "type": "module".
- Generate the first version with pm2 ecosystem and edit that, instead of writing the shape by hand.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
Related fixes
Servers
The shell cannot find pm2 after you installed it
bash: pm2: command not found
The shell found no pm2 file in any folder of PATH.
3 causes, each with a fixBack end
Node.js cannot start because the port is already taken
Error: listen EADDRINUSE: address already in use 127.0.0.1:8080
EADDRINUSE means another socket already listens on that port, so Node's listen() was refused.
4 causes, each with a fixBack end
process.env.NODE_ENV is undefined in a Node.js app
console.log(process.env.NODE_ENV) prints undefined
Node.js does not set NODE_ENV for you.
5 causes, each with a fixBack end
PM2 does not restart my Node.js app after it crashes
status stopped in pm2 list
PM2 restarts a crashed process on its own, so a process that stays down has a reason.
3 causes, each with a fixBack end
Loading a .env file into a PM2 ecosystem config fails or gives undefined values
[PM2][ERROR] File ecosystem.config.js malformated
PM2 only passes the env block of the config to your app.
4 causes, each with a fixBack end
PM2 keeps the old environment variables after restart --update-env
the app still prints the old value after pm2 restart
A plain pm2 restart reuses the environment stored at first start.
4 causes, each with a fix