Day: March 10, 2026

🐘 Fixing PostgreSQL Startup Issues on macOS (Homebrew): A Real-World Troubleshooting Guide

Introduction

Recently, I encountered an interesting PostgreSQL issue on my MacBook.

PostgreSQL was installed via Homebrew and worked perfectly on one macOS user account. However, when switching to another account on the same machine, I was unable to connect to PostgreSQL using psql.

The error looked like this:

psql postgres
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?

This article walks through the investigation, root cause analysis, and final solution.

Understanding the Error

When PostgreSQL starts successfully, it creates a Unix socket file:

/tmp/.s.PGSQL.5432

The psql client uses this socket by default to connect to the local PostgreSQL server.

The error indicates one of two possibilities:

  1. PostgreSQL is not running.
  2. PostgreSQL is running but not listening on the expected socket.

In my case, PostgreSQL was simply not running for the current macOS user account.

Initial Verification

Verify PostgreSQL Client Installation

which psql

Output:

/opt/homebrew/bin/psql

Check version:

psql --version

Output:

psql (PostgreSQL) 14.17 (Homebrew)

This confirmed that PostgreSQL client tools were correctly installed.

Verify Installed PostgreSQL Version

brew list | grep postgres

Output:

postgresql@14

Check Whether PostgreSQL Is Running

pg_isready

Output:

/tmp:5432 - no response

This confirmed that PostgreSQL was not accepting connections.

Manual Startup Worked

Interestingly, PostgreSQL could be started manually:

/opt/homebrew/opt/postgresql@14/bin/pg_ctl \
  -D /opt/homebrew/var/postgresql@14 \
  -l /opt/homebrew/var/log/postgresql.log start

Output:

waiting for server to start.... done
server started

This was a critical clue.

It told us:

  • PostgreSQL binaries were healthy.
  • Database files were healthy.
  • Data directory was healthy.
  • The issue was likely related to Homebrew services or macOS LaunchAgents.

Investigating Homebrew Services

Checking service status:

brew services list

Output:

Name           Status    User
postgresql@14  error 78  abhilash

Attempting to start the service:

brew services start postgresql@14

Result:

Bootstrap failed: 5: Input/output error
launchctl bootstrap gui/501

This indicated a problem with the macOS LaunchAgent used by Homebrew.

Root Cause

Homebrew services rely on macOS launchctl.

Each macOS user account gets its own LaunchAgents configuration.

Although PostgreSQL was installed globally under Homebrew, the LaunchAgent configuration for this specific user account had become corrupted or stale.

As a result:

  • Manual startup worked.
  • Automatic startup through Homebrew failed.

Fixing the LaunchAgent

Stop Existing Service

brew services stop postgresql@14

Remove Existing LaunchAgent

rm ~/Library/LaunchAgents/homebrew.mxcl.postgresql@14.plist

Clean Up Homebrew Services

brew services cleanup

Verify Ownership

ls -ld /opt/homebrew/var/postgresql@14

If ownership is incorrect:

sudo chown -R $(whoami):staff /opt/homebrew/var/postgresql@14

Recreate the Service

After cleanup:

brew services start postgresql@14

Output:

Successfully started `postgresql@14`

Checking status:

brew services list

Output:

postgresql@14 started

Success!

Verifying PostgreSQL Is Running

pg_isready

Output:

/tmp:5432 - accepting connections

Connecting:

psql postgres

Output:

postgres=#

PostgreSQL was now functioning normally.

Understanding a New Error

While reviewing PostgreSQL logs, I noticed:

FATAL: database "abhilash" does not exist

At first glance, this looked concerning.

However, this is normal behavior.

When you run:

psql

PostgreSQL automatically tries to connect to a database matching your operating system username.

For example:

macOS username = abhilash

PostgreSQL attempts:

CONNECT TO abhilash;

Since that database didn’t exist, PostgreSQL logged:

FATAL: database "abhilash" does not exist

Creating a Personal Database

To make plain psql work:

CREATE DATABASE abhilash;

Now simply running:

psql

works because PostgreSQL can find a matching database.

Key Lessons Learned

1. Verify Whether PostgreSQL Is Actually Running

pg_isready

is often the fastest diagnostic tool.

2. Manual Startup Helps Isolate the Problem

If pg_ctl start works, your PostgreSQL installation and data files are probably fine.

3. Homebrew Services Depend on macOS LaunchAgents

A corrupted LaunchAgent can prevent PostgreSQL from auto-starting even when PostgreSQL itself is healthy.

4. Don’t Reinstall Immediately

Many developers jump directly to:

brew uninstall postgresql
brew install postgresql

In this case, reinstalling would not have fixed the issue and could have introduced additional problems.

5. Read the PostgreSQL Logs

Logs quickly reveal whether you’re dealing with:

  • Permission issues
  • Missing databases
  • Port conflicts
  • Startup failures
  • Authentication errors

Final Verification Checklist

brew services list
pg_isready
psql postgres

Expected results:

postgresql@14 started
/tmp:5432 - accepting connections
postgres=#

At this point, PostgreSQL is healthy and configured to start automatically after reboot.

Conclusion

What initially appeared to be a PostgreSQL installation problem turned out to be a macOS LaunchAgent issue specific to one user account.

By methodically checking:

  • PostgreSQL installation
  • Server status
  • Homebrew services
  • LaunchAgent configuration
  • PostgreSQL logs

we were able to restore automatic startup without reinstalling PostgreSQL or risking data loss.

This experience serves as a reminder that startup problems are often service-management issues rather than database issues.

Happy Debugging! 🚀