louislam/uptime-kuma · error · Error

PM2 process '${processName}' was not found.

Error message

PM2 process '${processName}' was not found.

What it means

The PM2 monitor resolves the target by calling getPM2ProcessList() and matching monitor.system_service_name against either item.name or item.id. If no entry satisfies the predicate, the process does not exist in the PM2 process list the monitor can see, so it throws with the trimmed name interpolated. This is a lookup failure, not a PM2 daemon error.

Source

Thrown at server/monitor-types/pm2.js:21

const { getPM2ProcessList } = require("../util/pm2");

class PM2MonitorType extends MonitorType {
    name = "pm2";
    description = "Checks if a PM2 process is online.";

    /**
     * Check the PM2 process status.
     * @param {object} monitor The monitor object containing monitor.system_service_name.
     * @param {object} heartbeat The heartbeat object to update.
     * @returns {Promise<void>}
     */
    async check(monitor, heartbeat) {
        const processName = (monitor.system_service_name || "").trim();
        const processList = await getPM2ProcessList();
        const entry = processList.find((item) => item.name === processName || item.id === processName);

        if (!entry) {
            throw new Error(`PM2 process '${processName}' was not found.`);
        }

        if (entry.status === "online") {
            heartbeat.status = UP;
            heartbeat.msg = `PM2 process '${processName}' is online.`;
            return;
        }

        throw new Error(`PM2 process '${processName}' is ${entry.status}.`);
    }
}

module.exports = {
    PM2MonitorType,
};

View on GitHub (pinned to 6b5ea01557)

Solutions

1. Run `pm2 list` (or `pm2 jlist`) on the host the monitor watches and copy the exact `name` or `id` shown.
2. Update monitor.system_service_name to match exactly (case-sensitive, including spaces/hyphens).
3. Ensure the Uptime Kuma process and the PM2 daemon share the same PM2 home / socket (PM2_HOME or the same user).
4. Confirm the process is actually managed by PM2 and not by another supervisor.

Example fix

// before
monitor.system_service_name = "my app";
// after  (matches `pm2 list` name exactly)
monitor.system_service_name = "my-app";

const { getPM2ProcessList } = require('...pm2-helper');
async function validatePm2Name(name) {
  const list = await getPM2ProcessList();
  const names = new Set(list.map(p => `${p.name}|${p.id}`));
  if (!list.some(p => p.name === name || p.id === name)) {
    throw new Error(`PM2 name '${name}' not in [${[...names].join(', ')}]`);
  }
}

function isPm2EntryMatch(entry, name) {
  return !!entry && (entry.name === name || entry.id === name);
}

try {
  await pm2Monitor.check(monitor, heartbeat);
} catch (e) {
  if (/was not found/.test(e.message)) {
    // surface the actual PM2 list to the user for correction
    log.warn('Available PM2 processes:', await getPM2ProcessList());
  }
  throw e;
}

When it happens

Trigger: monitor.system_service_name does not equal any running PM2 process's name or id. Causes: typo in the field, process not under PM2, PM2 daemon the monitor talks to is a different daemon/instance, or the field is empty after trim (matches nothing).

Common situations: Mis-typed process name, monitoring a process managed by systemd instead of PM2, running Uptime Kuma in a container where the PM2 socket is not shared with the host PM2, or renaming a PM2 process after creating the monitor.

Related errors

• PM2 process name is required.
• PM2 process '${processName}' is ${entry.status}.
• Invalid db-config.json, type must be a string
• Unknown Database type: ${dbConfig.type}
• Failed to load docker host config

AI-assisted analysis of louislam/uptime-kuma@6b5ea01557 (2026-08-12). Data as JSON: /api/errors/f5f042d73446378d. Report an issue: GitHub.