How I Fixed a Sudden PostgreSQL Connection Error on macOS (And What I Learned)

One day, everything was working fine. The next, my Strapi backend threw a PostgreSQL connection error and refused to run. Here's what happened — and how I fixed it.

I was working on a project using:

• Strapi as the backend

• PostgreSQL 14, installed via Homebrew

• Running on macOS (Apple Silicon)

Everything had been working smoothly for weeks. I would simply run:

pnpm develop

And Strapi would spin up, connect to the database, and serve my API.

Until one day… it didn't.

---

Out of nowhere, Strapi crashed at startup with:

Error: connect ECONNREFUSED 127.0.0.1:5432

Which usually means PostgreSQL isn’t running. So I tried starting it:

brew services start postgresql@14

But then, I hit this mysterious error:

Bootstrap failed: 5: Input/output error
Error: Failure while executing; /bin/launchctl bootstrap ...

At this point, PostgreSQL was officially ghosting me.

I came across several Stack Overflow threads, including this one:

🔗 psql error: connection to server on socket “/tmp/.s.PGSQL.5432” failed: No such file or directory

It offered some hints, but I couldn’t find a complete, step-by-step fix that applied cleanly to my setup. So I decided to document my process — and what worked — here for others.

---

The Rabbit Hole: Digging Into the Issue

I ran:

psql postgres

And got this classic:

psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory
Is the server running locally and accepting connections on that socket?

Translation: PostgreSQL wasn’t listening on its default port or Unix socket.

So I tried starting it manually:

/opt/homebrew/opt/postgresql@14/bin/postgres -D /opt/homebrew/var/postgresql@14

But that gave me:

FATAL: lock file "postmaster.pid" already exists
HINT: Is another postmaster (PID XXXX) running in data directory?

The Real Cause: An Unexpected System Shutdown

Turns out, PostgreSQL leaves behind a lock file (postmaster.pid) to prevent multiple instances from starting at once. That’s totally normal — it’s how PostgreSQL ensures data integrity.

But in my case, this lock became a ghost — a stale file left behind after my system unexpectedly shut down while my local Strapi server was still running. PostgreSQL didn’t get a chance to clean up, so the next time it tried to boot, it thought another instance was already running — and refused to start.

Classic "zombie lock" scenario.

---

The Fix (Step-by-Step)

Here’s how I fixed it:

1. Kill any lingering PostgreSQL processes

Check if the PID in the lock file is actually running:

ps -p <PID>

If not, safely remove the lock:

rm /opt/homebrew/var/postgresql@14/postmaster.pid

2. Start PostgreSQL manually

/opt/homebrew/opt/postgresql@14/bin/postgres -D /opt/homebrew/var/postgresql@14

If you see logs like:

LOG: database system is ready to accept connections

You're good!

3. Try connecting with your system username

psql -h 127.0.0.1 -U $(whoami)

New error:

FATAL: database "<your-username>" does not exist

Yep. PostgreSQL tries to connect to a DB with your username by default.

4. Create the missing user and/or DB

If you're missing the postgres role:

CREATE ROLE postgres WITH LOGIN SUPERUSER PASSWORD 'postgres';

If you're missing your DB:

CREATE DATABASE yourusername;

---

Common PostgreSQL Errors (And What They Mean)

Here are a few more PostgreSQL errors I've encountered — and their fixes:

psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory

Cause: PostgreSQL server isn't running, or its socket file was never created.

Fix:

• Start PostgreSQL:

    brew services start postgresql@14
  

• Or manually:

    /opt/homebrew/opt/postgresql@14/bin/postgres -D /opt/homebrew/var/postgresql@14
  

FATAL: role "postgres" does not exist

Cause: You haven’t created the default postgres superuser.

Fix:

CREATE ROLE postgres WITH LOGIN SUPERUSER PASSWORD 'postgres';

FATAL: database "<your-username>" does not exist

Cause: PostgreSQL tries to connect to a database matching your system username.

Fix:

CREATE DATABASE <your-username>;

Or connect with a specific DB:

psql -U <user> -d <your-database>

FATAL: lock file "postmaster.pid" already exists

Cause: PostgreSQL thinks it’s still running because a lock file wasn’t cleaned up.

Fix:

ps -p <PID>
rm /opt/homebrew/var/postgresql@14/postmaster.pid

Error: connect ECONNREFUSED 127.0.0.1:5432

Cause: Your app (Strapi, Prisma, etc.) can’t reach PostgreSQL.

Fix:

• Make sure PostgreSQL is running.

• Check your .env credentials.

• Restart your app and DB service.

---

What I Learned

• postmaster.pid is PostgreSQL’s lockfile — if left behind, you may get ghost failures.

• Homebrew-based services can fail silently after OS or DB updates.

• The postgres user/role is not guaranteed to exist — always check.

• Don't rely on GUI apps to tell you if PostgreSQL is really up.

---

How to Prevent This in the Future

• Always stop PostgreSQL gracefully before rebooting or upgrading:

    brew services stop postgresql@14
  

• Keep backups of:

  • Your .env config

  • Custom DB roles

  • Manual install locations

• After reinstalling:

  • Create needed roles (postgres)

  • Create missing databases

  • Restart the DB and test with psql

---

Bonus Tip: Manual Connection Cheat Sheet

psql -h 127.0.0.1 -U postgres -d postgres

Sample .env:

DATABASE_HOST=127.0.0.1
DATABASE_PORT=5432
DATABASE_NAME=postgres
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=postgres

---

Conclusion

This PostgreSQL issue caught me off guard — but with some digging, I learned how to properly recover and reconnect. Hopefully, this post saves you the same trouble. I couldn’t find one resource that tied it all together… so here’s mine.

Happy debugging.