[Fixed] FATAL: lock file “postmaster.pid” already exists in PostgreSQL: Step-by-Step Troubleshooting Guide

Quick Summary: The error FATAL: lock file "postmaster.pid" already exists (often followed by HINT: Is another postmaster (PID <num>) running in data directory?) occurs when PostgreSQL refuses to start because it detects an existing PID lock file in its data directory. This typically happens after an unexpected power loss, a macOS/Linux system crash, an OOM kill, or an abrupt Docker container termination that left behind a stale postmaster.pid file.

Understanding the Root Causes

PostgreSQL writes a postmaster.pid file inside its data directory (PGDATA) upon startup to record the active server Process ID, data directory path, and shared memory keys. This prevents two PostgreSQL instances from writing to the same data files simultaneously, which would cause severe index and heap corruption. The startup block occurs due to:

  • Unclean Shutdown or System Crash: A sudden OS reboot, battery drain, or kill -9 signal prevented PostgreSQL from cleaning up postmaster.pid during shutdown.
  • Docker Volume Stale Locks: Stopping a PostgreSQL container forcefully or mounting a persistent host volume after an unexpected Docker Desktop crash, leaving an orphaned PID file inside /var/lib/postgresql/data.
  • An Active Instance is Actually Running: Attempting to launch a second PostgreSQL server (e.g., via Homebrew or pg_ctl) against a data directory already managed by a background service.

Step 1: Quick Triage – Verify No PostgreSQL Process is Running

Critical Warning: Never delete postmaster.pid without first confirming that no postgres process is actively using the data directory. Check the running processes and inspect the PID recorded inside the lock file:

# 1. Inspect the contents of postmaster.pid (first line is the recorded PID)
cat /usr/local/var/postgres/postmaster.pid
# (On Linux/Docker, check /var/lib/postgresql/15/main/postmaster.pid or $PGDATA/postmaster.pid)

# 2. Check if any postgres processes are currently active on the machine
ps aux | grep postgres

# 3. On macOS Homebrew, check brew services status
brew services list | grep postgresql

# 4. On Linux systemd, check the service state
sudo systemctl status postgresql

If a live postgres process is running and matches the PID in the file, stop it cleanly using pg_ctl stop or systemctl stop postgresql rather than deleting the lock file.

Step 2: Safely Remove the Stale postmaster.pid File

Once you have confirmed that no active PostgreSQL process is running against that data directory, back up or remove the stale lock file and restart the database:

# Option A: macOS (Homebrew PostgreSQL - Apple Silicon / Intel)
# Common data directories: /opt/homebrew/var/postgresql@15 or /usr/local/var/postgres
rm -f /opt/homebrew/var/postgresql@15/postmaster.pid
brew services restart postgresql@15

# Option B: Linux (Ubuntu/Debian)
sudo rm -f /var/lib/postgresql/15/main/postmaster.pid
sudo systemctl start postgresql

# Option C: Docker / Docker Compose with persistent volume
# Stop the failing container first
docker compose down
# Remove the stale PID file from the mounted host directory or named volume:
docker run --rm -v my_pgdata:/var/lib/postgresql/data alpine rm -f /var/lib/postgresql/data/postmaster.pid
docker compose up -d

Step 3: Resolve Shared Memory or Socket Leftovers (If Startup Still Fails)

If PostgreSQL still fails to start after removing postmaster.pid, check for orphaned socket lock files in /tmp or /var/run/postgresql and inspect the startup logs:

# Check for stale Unix socket lock files
ls -la /tmp/.s.PGSQL.* /var/run/postgresql/

# Remove stale socket files only if no postgres process is running
sudo rm -f /tmp/.s.PGSQL.5432*

# Inspect PostgreSQL startup logs for permission or disk space errors
# Linux:
sudo tail -n 50 /var/log/postgresql/postgresql-15-main.log
# macOS Homebrew:
tail -n 50 /opt/homebrew/var/log/postgresql@15.log

Verification & Testing Steps

Confirm that PostgreSQL starts cleanly, generates a fresh postmaster.pid, and accepts client connections:

# 1. Verify PostgreSQL service is active and listening on port 5432
pg_isready -h localhost -p 5432
# Expected output: localhost:5432 - accepting connections

# 2. Confirm a fresh postmaster.pid was created with the new PID
head -n 1 /opt/homebrew/var/postgresql@15/postmaster.pid

# 3. Connect via psql to test query execution
psql -U postgres -c "SELECT version();"

Troubleshooting Summary Comparison

Environment Default postmaster.pid Location Recommended Recovery Steps
macOS (Homebrew Apple Silicon) /opt/homebrew/var/postgresql@<ver>/postmaster.pid Verify ps aux empty, remove PID file, brew services restart
Ubuntu / Debian Linux /var/lib/postgresql/<ver>/main/postmaster.pid Confirm service stopped, remove PID file, systemctl start postgresql
Docker Persistent Volume /var/lib/postgresql/data/postmaster.pid Run temporary Alpine container on volume to delete stale PID file
Active Duplicate Instance Matches live PID in ps aux Do NOT delete PID file; stop existing instance cleanly first

Leave a Reply