Unitech/pm2 · error · Error

module package.json not defined

Error message

module package.json not defined

What it means

StartModule loads and launches a PM2 module from its package.json. It needs either opts.cmd or opts.package (both are alternate keys pointing at the package.json path) so it can require() it. With neither set there is no file to load, so it throws immediately.

Source

Thrown at lib/API/Modules/NPM.js:346

  if (!app_name) throw new Error('No app_name defined');

  var module_conf = Configuration.getAllSync();

  var additional_env = {};

  if (!module_conf[app_name]) {
    additional_env = {};
    additional_env[app_name] = {};
  }
  else {
    additional_env = Common.clone(module_conf[app_name]);
    additional_env[app_name] = JSON.stringify(module_conf[app_name]);
  }
  return additional_env;
}

function StartModule(CLI, opts, cb) {
  if (!opts.cmd && !opts.package) throw new Error('module package.json not defined');
  if (!opts.development_mode) opts.development_mode = false;

  var package_json = require(opts.cmd || opts.package);

  /**
   * Script file detection
   * 1- *apps* field (default pm2 json configuration)
   * 2- *bin* field
   * 3- *main* field
   */
  if (!package_json.apps && !package_json.pm2) {
    package_json.apps = {};

    if (package_json.bin) {
      var bin = Object.keys(package_json.bin)[0];
      package_json.apps.script = package_json.bin[bin];
    }
    else if (package_json.main) {

View on GitHub (pinned to 31adee8048)

Solutions

1. Set opts.cmd (or opts.package) to the absolute path of the module's package.json.
2. If using the CLI, ensure the module name/URL resolves to a directory containing a package.json.

Example fix

// before
StartModule(CLI, { development_mode: true }, cb);
// after
StartModule(CLI, { cmd: '/abs/path/to/module/package.json', development_mode: true }, cb);

if (!opts.cmd && !opts.package) {
  return cb(new Error('Pass opts.cmd or opts.package pointing to the module package.json'));
}

function hasPackageRef(opts) {
  return Boolean(opts && (opts.cmd || opts.package));
}

When it happens

Trigger: Calling the module-start flow programmatically with an opts object that has neither cmd nor package (e.g. only development_mode, safe, or other metadata keys).

Common situations: Programmatic module start with the wrong options shape; passing a directory or tarball but forgetting to set the package.json path on opts.

Related errors

• No app_name defined
• Attribute name should be present
• Attribute version should be present
• Cannot find package.json

AI-assisted analysis of Unitech/pm2@31adee8048 (2026-08-13). Data as JSON: /api/errors/62131afc51337cac. Report an issue: GitHub.