Non-zero exit code restart loop in PM2 process manager

Direct Answer

PM2 exposes a PM2_JSON environment variable containing a restart_count field that increments on each restart. A fresh start shows restart_count: 0; a PM2-initiated restart shows restart_count > 0. However, this mechanism is undocumented, version-dependent, and unreliable in containerized deployments. The robust solution is application-level idempotency (idempotency keys, unique constraints, or deduplication logic) rather than relying on process-manager signals.

How PM2_JSON Works (When It Works)

On each process launch, PM2 injects a JSON string into process.env.PM2_JSON. Typical structure includes:

{
  "name": "my-app",
  "pm_id": 0,
  "restart_count": 3,
  "status": "online",
  "exit_code": 1
}

In your entry script you can parse it:

let restartCount = 0;
try {
  const meta = JSON.parse(process.env.PM2_JSON || '{}');
  restartCount = typeof meta.restart_count === 'number' ? meta.restart_count : 0;
} catch { /* ignore parse errors */ }

const isFreshStart = restartCount === 0;
console.log(isFreshStart ? 'Fresh start' : `Restart #${restartCount}`);

This lets you skip non-idempotent initialization on restarts, but only if the variable survives your deployment pipeline.

Why PM2_JSON Is Not a Reliable Discriminator

• Undocumented and unstable — field names and presence change between PM2 v4, v5, and v6 without notice.
• Stripped in containers — Docker, Kubernetes, or PM2-to-container bridges often drop or rewrite environment variables.
• No trigger detail — it tells you that a restart occurred, not why (crash, SIGTERM, pm2 restart, config change).
• Race with logging — the variable is set before your code runs, but if the process crashes before parsing, you lose the context.

Recommended Idempotency Patterns

Design the write path to be safely repeatable regardless of how the process started:

1. Idempotency keys — generate a deterministic key (e.g., hash(userId + action + timestampMinute)) and store it with a unique constraint in the database. Duplicate attempts become no-ops.
2. Database-level deduplication — use INSERT ... ON CONFLICT DO NOTHING (PostgreSQL) or INSERT IGNORE (MySQL) with a unique index on the business key.
3. Outbox pattern — write intent records to an outbox table within the same transaction as the business data; a separate publisher processes the outbox exactly once.
4. Optimistic locking — include a version column; reject writes where the version has changed since read.

PM2 Configuration to Reduce Restart Noise

While not a substitute for idempotency, these settings make restart loops observable and bounded:

module.exports = {
  apps: [{
    name: 'my-app',
    script: 'index.js',
    max_restarts: 5,          // stop after 5 crashes
    restart_delay: 5000,      // 5s backoff between attempts
    min_uptime: 10000,        // must stay alive 10s to reset counter
    watch: false,             // disable in production
    env: {
      NODE_ENV: 'production'
    }
  }]
};

With max_restarts set, PM2 will eventually mark the process as errored instead of looping indefinitely, surfacing the root cause in pm2 logs and monitoring.

One Diagnostic Detail Needed

What is your PM2 version (pm2 --version) and deployment target (bare metal, Docker, Kubernetes, PM2-runtime)? The exact PM2_JSON schema and whether the variable reaches your process depend on both.