Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

PM2 says the ecosystem file is malformated and refuses to start

Error[PM2][ERROR] File ecosystem.config.js malformated

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

  • Applies to PM2 6, Node.js 22, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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'))"
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2SyntaxError: Unexpected token 'export', or ERR_REQUIRE_ASYNC_MODULE, right under the malformated lineThe file uses ES module syntax or top-level awaitFix
    3. 3The file is called ecosystem.json, ecosystem.yml or similar, but it contains module.exports or require()JavaScript saved in a .json or .yml fileFix

What does the error look like?

  • [PM2][ERROR] File ecosystem.config.js malformated
  • Error [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.js

Confirmed by github.com

Did this fix it?

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

2Fix

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

3Verify

pm2 start accepts the file and the process shows as online.

pm2 status

Confirmed by nodejs.org

Did this fix it?

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

3Verify

PM2 prints a table with your app instead of the malformated line.

pm2 status

Confirmed by github.com

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.