Next.js app fails to run in PM2 cluster mode within Docker container

[vgulerianb]

I'm encountering an issue running a Next.js application in a Docker container using PM2's cluster mode. While the application runs successfully in fork mode, it fails when attempting to use cluster mode.

Current Behavior

• Application fails to start in cluster mode with PM2 inside Docker
• Works fine in fork mode
• When executing into the container and running pm2 start manually, it works in cluster mode
• Only fails when using pm2-runtime which is required for Docker

Environment

• Next.js version: 14.2.3
• Node.js version: 19
• PM2 for process management
• Docker containerized environment

ecosystem.config.js

module.exports = {
  apps: [
    {
      name: "nextjs",
      cwd: "./",
      script: "node_modules/.bin/next",
      args: "start",
      // instances: "max",
      // exec_mode: "cluster",
      autorestart: true,
      max_memory_restart: "1G",
      env: {
        PORT: 3000,
        NODE_ENV: "production",
        wait_ready: true,
        listen_timeout: 10000,
        NEXT_SKIP_ENV_VALIDATION: true,
        SKIP_ENV_VALIDATION: true,
      },
    },
  ],
};

Dockerfile CMD

CMD ["pm2-runtime", "/ecosystem.config.js", "--no-daemon"]

Error Logs

No such directory exists as the project root: /ecosystem.config.js
2025-02-17T10:28:53: PM2 log: App [nextjs:1] online
2025-02-17T10:28:53: PM2 error: Cancelling versioning data parsing
2025-02-17T10:28:53: PM2 log: App name:nextjs id:2 disconnected
2025-02-17T10:28:53: PM2 log: App [nextjs:2] exited with code [1] via signal [SIGINT]
2025-02-17T10:28:53: PM2 log: App [nextjs:2] starting in -cluster mode-

Steps to Reproduce

1. Build and run the Docker container with the above configuration
2. Enable cluster mode in ecosystem.config.js by uncommenting:

   instances: "max",
   exec_mode: "cluster",
   

3. Application fails to start in cluster mode

Additional Information

• The application runs successfully in fork mode
• Manual pm2 start inside the container works in cluster mode
• Issue only occurs with pm2-runtime in cluster mode
• Using Next.js 14.2.3 with Node.js 19

Any assistance or guidance would be greatly appreciated.

[rohankamble103]

Reason

The error No such directory exists as the project root: /ecosystem.config.js means PM2 can’t find your config file. You're using /ecosystem.config.js (absolute path), but it should be relative to your working directory or the actual path inside the container.

Solution

**Change the command in the CMD instruction to start the app change it is not able to find the ecosystem.config.js and then create the docker image again and then try to run the image.

Replace "CMD ["pm2-runtime", "/ecosystem.config.js"]" to

CMD ["pm2-runtime", "ecosystem.config.js"]

Or you can also give the absolute path where you have stored the ecosystem.config.js

[dpidan]

I had the same problem.

Some facts:

• I know pm2 can find the config file because it's logging based on app name set only in the config file.
• I also know it can find the script file because I get output from my script. Also, when I change to a bad script filename, pm2 errors as expected.
• Specs:
  • Node.js v22.12.9
  • pm2 v6.0.6

This only happens in cluster mode. When I remove exec_mode: 'cluster' line, everything works as expected.

The errors didn't make any sense. it would look like the app started, but then would immediately get an exit 1 and then try to restart the app. This would loop endlessly.

I couldn't find anything in the docs around this. Apparently, though, when using pm2-runtime or pm2-docker, you have to start a pm2 instance first. I was able to do this by running pm2 -v before running pm2-runtime. I'd bet I'm overlooking some setting or callout in documentation, but I've run out of time to continue investigating.

What am I missing?