PM2 is one of the most popular process managers for Node.js applications, but many developers encounter a frustrating issue where PM2 suddenly starts using /tmp/.pm2 instead of the real home directory. This problem causes services to show as “inactive (dead)” and processes to disappear after system reboots, leaving applications offline and users confused about what went wrong.

Understanding the PM2 Home Directory Problem

When PM2 operates correctly, it should use your user’s home directory (typically /home/username/.pm2) to store configuration files, process lists, and logs. However, under certain conditions, PM2 can fallback to using /tmp/.pm2, which creates a cascade of problems that can disrupt your entire application deployment strategy.

The core issue manifests when you see pm2_home=/tmp/.pm2 in your PM2 status output. This seemingly small detail indicates that PM2 is operating from a temporary directory that gets cleared on system reboots, making all your process management configurations ephemeral.

Why PM2 Switches to /tmp Directory

Primary Causes

The PM2 home directory issue typically stems from one or more of these common scenarios:

Running PM2 with sudo permissions - When you execute PM2 commands with sudo, the environment variables from your user session get lost, and PM2 automatically falls back to /tmp/.pm2 as a safe default location.

Missing PM2_HOME environment variable - If PM2_HOME isn’t exported in your shell configuration before using PM2, the process manager may not know where to look for its configuration files.

System reboots clearing /tmp - Most Linux distributions clear the /tmp directory on boot, which means any PM2 daemon or configuration stored there disappears completely.

Environmental Factors

Several environmental factors can contribute to this problem:

User permission issues when PM2 tries to access the home directory
Shell configuration problems where environment variables aren’t properly set
Systemd service misconfiguration with incorrect user home paths
Container or virtual machine environments with non-standard user setups

Symptoms and Impact

Common Symptoms

When PM2 is using the wrong home directory, you’ll typically experience these symptoms:

PM2 daemon disappears after system reboots
Services show “inactive (dead)” in systemctl status
pm2 save command appears to work but doesn’t persist processes
pm2 startup generates incorrect systemd service files
Applications fail to restart automatically after reboots
Process lists vanish when checking pm2 list

Real-World Impact

The consequences of this issue can be severe for production environments:

Downtime when applications don’t restart after server maintenance
Manual intervention required to restart processes after each reboot
Inconsistent deployment environments across different servers
Monitoring and alerting failures when processes disappear
Data loss if applications rely on persistent PM2 state

Complete Troubleshooting Guide

Step 1: Diagnose the Current PM2 Home

First, verify where PM2 is currently operating from:

# Check current PM2 home directory
echo $PM2_HOME

# Check PM2 status and home location
pm2 status
pm2 info

# Look for pm2_home=/tmp/.pm2 in the output

If you see /tmp/.pm2 anywhere in the output, you’ve confirmed the problem.

Step 2: Set Permanent PM2 Home Directory

The most critical fix is to permanently set the PM2_HOME environment variable:

# Add PM2_HOME to your shell configuration
echo 'export PM2_HOME=/home/secureuser/.pm2' >> ~/.bashrc

# Apply the changes immediately
source ~/.bashrc

# Verify the setting took effect
echo $PM2_HOME

Important: Replace secureuser with your actual username. This ensures PM2 always knows where to find its configuration files.

Step 3: Clean Up Existing PM2 Processes

Stop all existing PM2 processes and clean up the temporary directory:

# Stop all PM2 processes
pm2 kill

# Remove the temporary PM2 directory (optional but recommended)
sudo rm -rf /tmp/.pm2

# Verify PM2 is completely stopped
ps aux | grep pm2

Step 4: Restart PM2 with Correct Home Directory

Start PM2 fresh with the correct home directory:

# Start PM2 with explicit home directory
PM2_HOME=/home/secureuser/.pm2 pm2 start npm --name your-app-name -- start -- -p 3000

# Verify PM2 is using the correct home
pm2 status

Step 5: Save Processes Permanently

Now that PM2 is using the correct directory, save your process list:

# Save the current process list
pm2 save

# Verify the save worked
ls -la ~/.pm2/dump.pm2

You should see the dump file in your home directory, not in /tmp.

Step 6: Generate Correct Systemd Service

Create a proper systemd service that respects your PM2 home:

# Generate systemd service with correct user and home
pm2 startup systemd -u secureuser --hp /home/secureuser

# Enable the service
sudo systemctl enable pm2-secureuser

# Start the service
sudo systemctl start pm2-secureuser

# Check service status
sudo systemctl status pm2-secureuser

Step 7: Verify Complete Fix

Test that everything works correctly:

# Check PM2 processes
pm2 list

# Verify service is active
sudo systemctl status pm2-secureuser

# Test reboot persistence (simulate)
sudo systemctl restart pm2-secureuser
pm2 list

Advanced Troubleshooting Techniques

Checking Systemd Service Configuration

Examine the generated systemd service file to ensure it’s correct:

# View the systemd service file
sudo cat /etc/systemd/system/pm2-secureuser.service

# Look for correct Environment=PM2_HOME line
# Should show: Environment=PM2_HOME=/home/secureuser/.pm2

Manual Systemd Service Creation

If the automatic generation fails, create the service manually:

sudo tee /etc/systemd/system/pm2-secureuser.service > /dev/null <<EOF
[Unit]
Description=PM2 process manager
Documentation=https://pm2.keymetrics.io/
After=network.target

[Service]
Type=forking
User=secureuser
LimitNOFILE=infinity
LimitNPROC=infinity
LimitCORE=infinity
Environment=PATH=/usr/bin:/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
Environment=PM2_HOME=/home/secureuser/.pm2
PIDFile=/home/secureuser/.pm2/pm2.pid
ExecStart=/usr/lib/node_modules/pm2/bin/pm2 resurrect
ExecReload=/usr/lib/node_modules/pm2/bin/pm2 reload all
ExecStop=/usr/lib/node_modules/pm2/bin/pm2 kill
Restart=always

[Install]
WantedBy=multi-user.target
EOF

# Reload systemd and enable
sudo systemctl daemon-reload
sudo systemctl enable pm2-secureuser
sudo systemctl start pm2-secureuser

Log Analysis for Persistent Issues

Check PM2 and systemd logs for deeper insights:

# PM2 logs
pm2 logs

# Systemd service logs
sudo journalctl -u pm2-secureuser -f

# System boot logs for PM2-related issues
sudo journalctl -b | grep pm2

Prevention Strategies

Best Practices for PM2 Management

Implement these practices to prevent the PM2 home directory issue:

Always use the same user for PM2 operations to maintain consistent environment variables.

Never run PM2 with sudo unless absolutely necessary for system-level operations.

Always set PM2_HOME in shell configuration before using PM2 commands.

Verify PM2_HOME before critical operations like deployments or reboots.

Environment Setup Script

Create a setup script to ensure consistent PM2 environment:

#!/bin/bash
# pm2-setup.sh - Ensure consistent PM2 environment

# Set user and home directory
USER_NAME=$(whoami)
PM2_HOME_DIR="/home/$USER_NAME/.pm2"

# Export PM2_HOME
export PM2_HOME="$PM2_HOME_DIR"

# Add to shell if not already present
if ! grep -q "PM2_HOME" ~/.bashrc; then
    echo "export PM2_HOME=$PM2_HOME_DIR" >> ~/.bashrc
    echo "PM2_HOME added to ~/.bashrc"
fi

# Create PM2 directory if it doesn't exist
mkdir -p "$PM2_HOME_DIR"

# Verify setup
echo "PM2_HOME: $PM2_HOME"
echo "PM2 version: $(pm2 --version)"
echo "Setup complete!"

Monitoring and Alerting

Implement monitoring to catch PM2 home directory issues early:

#!/bin/bash
# pm2-health-check.sh - Monitor PM2 health

USER_NAME=$(whoami)
EXPECTED_PM2_HOME="/home/$USER_NAME/.pm2"
CURRENT_PM2_HOME=$(pm2 show pm2 2>/dev/null | grep "pm2_home" | cut -d'=' -f2 || echo "")

if [[ "$CURRENT_PM2_HOME" != "$EXPECTED_PM2_HOME" ]]; then
    echo "ALERT: PM2 is using wrong home directory: $CURRENT_PM2_HOME"
    echo "Expected: $EXPECTED_PM2_HOME"
    # Add your alerting logic here (email, Slack, etc.)
    exit 1
fi

# Check if PM2 daemon is running
if ! pgrep -f "pm2" > /dev/null; then
    echo "ALERT: PM2 daemon is not running"
    exit 1
fi

echo "PM2 health check passed"
exit 0

Common Variations and Solutions

Docker Container Environments

In Docker containers, the PM2 home directory issue can be more complex:

# Dockerfile example
FROM node:18-alpine

# Create app user
RUN addgroup -g 1001 -S nodejs
RUN adduser -S nodejs -u 1001

# Set PM2_HOME in environment
ENV PM2_HOME=/home/nodejs/.pm2

# Install PM2 globally
RUN npm install -g pm2

# Create PM2 directory
RUN mkdir -p $PM2_HOME && chown -R nodejs:nodejs $PM2_HOME

USER nodejs
WORKDIR /app

# Copy and install dependencies
COPY package*.json ./
RUN npm ci --only=production

COPY . .

# Start application with PM2
CMD ["pm2", "start", "npm", "--name", "app", "--", "start"]

Multiple User Environments

When managing PM2 across multiple users:

# System-wide PM2 configuration
sudo tee /etc/profile.d/pm2.sh > /dev/null <<EOF
# Set PM2_HOME for all users
if [[ -n "\$HOME" ]] && [[ -d "\$HOME" ]]; then
    export PM2_HOME="\$HOME/.pm2"
fi
EOF

# Make it available immediately
source /etc/profile.d/pm2.sh

Cloud Platform Specifics

Different cloud platforms may require specific approaches:

AWS EC2: Ensure user data scripts set PM2_HOME correctly Google Cloud: Use startup scripts with proper environment variables DigitalOcean: Configure droplet user data to set PM2_HOME Azure: Use custom script extensions for PM2 environment setup

Performance and Optimization Considerations

PM2 Log Management

Proper log management prevents disk space issues:

# Configure PM2 log rotation
pm2 install pm2-logrotate

# Set log rotation settings
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 30
pm2 set pm2-logrotate:compress true

Memory and Process Limits

Optimize PM2 for production environments:

# Set process limits in systemd service
# Add to service file:
LimitNOFILE=65536
LimitNPROC=4096
MemoryMax=2G

Monitoring PM2 Performance

Implement comprehensive monitoring:

# PM2 monitoring dashboard
pm2 install pm2-server-monit

# Custom monitoring script
#!/bin/bash
# pm2-monitor.sh
while true; do
    pm2 monit --no-daemon
    sleep 300
done

FAQ

What causes PM2 to use /tmp/.pm2 instead of my home directory?

PM2 switches to /tmp/.pm2 primarily when it’s run with sudo permissions, which strips environment variables, or when the PM2_HOME environment variable isn’t properly set in the shell configuration. This can also happen during system reboots if the environment isn’t correctly configured in startup scripts or systemd services.

How do I permanently fix PM2 home directory issues?

The permanent fix involves setting the PM2_HOME environment variable in your shell configuration file (~/.bashrc or ~/.profile), stopping all PM2 processes, cleaning up any temporary directories, and restarting PM2 with the correct home directory. Then generate a new systemd service that explicitly uses the correct PM2_HOME path.

Why do my PM2 processes disappear after reboot?

Processes disappear after reboot because PM2 was using /tmp/.pm2, which gets cleared during system startup. The process list and configuration files stored in the temporary directory are lost, so PM2 starts with an empty process list and doesn’t know which applications to restart.

How do I check if PM2 is using the correct home directory?

Run echo $PM2_HOME to check the current environment variable, and use pm2 status or pm2 info to see where PM2 is actually operating from. Look for any references to /tmp/.pm2 in the output, which indicates the problem exists.

Can I run PM2 with sudo without causing this issue?

Running PM2 with sudo is not recommended as it typically causes environment variable loss. If you must use sudo for specific operations, always explicitly set the PM2_HOME environment variable in the command: sudo PM2_HOME=/home/user/.pm2 pm2 command.

How do I fix systemd service showing PM2 as inactive (dead)?

The systemd service shows as inactive because it’s trying to start PM2 with the wrong home directory. Regenerate the systemd service using pm2 startup systemd -u username --hp /home/username, then enable and restart the service with sudo systemctl enable pm2-username && sudo systemctl start pm2-username.

What should I do if pm2 save doesn’t persist my processes?

If pm2 save isn’t working, first verify PM2 is using the correct home directory with echo $PM2_HOME. Check if the dump file exists at ~/.pm2/dump.pm2. If PM2 is using /tmp/.pm2, follow the complete troubleshooting guide to fix the home directory issue first.

How do I prevent PM2 home directory issues in production environments?

Prevent these issues by always setting PM2_HOME in shell configurations, never running PM2 with sudo, using consistent user accounts, implementing monitoring scripts to check PM2 health, and ensuring systemd services have the correct environment variables configured.

Conclusion

Fixing PM2’s /tmp/.pm2 home directory issue is crucial for maintaining reliable Node.js application deployments. The problem stems from environment variable misconfiguration, particularly when PM2 is run with sudo or when PM2_HOME isn’t properly set in shell configurations.

By following the comprehensive troubleshooting guide outlined above, you can permanently resolve this issue and ensure your PM2 processes persist across reboots. The key steps involve setting the correct PM2_HOME environment variable, cleaning up temporary directories, restarting PM2 with the proper configuration, and generating accurate systemd services.

Implement the prevention strategies to avoid future occurrences, and consider setting up monitoring to catch any PM2 home directory issues early. With these practices in place, your Node.js applications will maintain consistent uptime and reliable process management.

For more Node.js deployment and process management best practices, explore our FastAPI production deployment guide and systemd complete guide.

Search Posts