Guides

Local service problems on macOS, one problem per page. Terminal fix first, ServeMon at the end.

• Check whether Postgres is running on a Mac

  Four ways to tell whether PostgreSQL is actually up on macOS: pg_isready, brew services list and info, lsof on port 5432, and docker ps, plus why a running process is not the same as a server that answers.

• brew services says started but the service is not running

  Why brew services list reports started while Postgres, Redis, or MySQL refuses connections: how to read the service log, check launchd's exit code, clear a stale pid file, and fix a broken plist.

• Where the Postgres data directory is on a Mac

  Where Homebrew, Postgres.app, and Docker keep the PostgreSQL data directory, postgresql.conf, and the log, and the SHOW commands that make the running server tell you.

• Could not connect to Redis at 127.0.0.1:6379: Connection refused

  Check with redis-cli ping, start the Homebrew service, read redis.log, check bind and port in redis.conf, and publish the port if Redis is in Docker.

• Can't connect to local MySQL server through socket vs TCP on 3306

  localhost means the socket, 127.0.0.1 means TCP, Docker has no host socket, and how to check each.

• Homebrew Postgres and a Docker container both on 5432

  How to see which one owns the port, why psql and your app can hit different databases, and how to stop one or move the container to 5433.

• Which local service is Docker, Homebrew, or a bare binary

  Read the process behind the port with lsof and ps, match its path to Homebrew's Cellar or Postgres.app, check docker ps for containers, and compare with brew services list.

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

  No server has created the socket file: start Postgres with brew services, read its log if it dies on start, clear a stale postmaster.pid safely, and use -h 127.0.0.1 for Docker.

• MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017

  Start mongod with brew services start mongodb-community, use 127.0.0.1 instead of localhost for the ::1 variant, read mongo.log if it dies on start, and publish the port if MongoDB is in Docker.

• Upgrade Homebrew Postgres to a new major version (postgresql@16 to @17)

  Each postgresql@ formula has its own data directory: copy the data across with pg_dumpall or pg_upgrade --clone, stop the old service, and move PATH and brew link to the new version's keg-only binaries.

• ERROR 1045: Access denied for user 'root'@'localhost' with Homebrew MySQL

  Read using password: NO versus YES, why Homebrew root starts with no password, why MariaDB root needs the socket, and how to reset the root password with --init-file.

• psql: FATAL: role "postgres" does not exist with Homebrew Postgres

  Homebrew's initdb makes your macOS user the superuser: connect as yourself with -d postgres, create the role with createuser -s postgres, fix database "you" does not exist with createdb, and tell Homebrew from a Docker container by the error line.

• ERROR! The server quit without updating PID file (Homebrew MySQL)

  Read the hostname.err log in the data directory, then fix the real cause: another mysqld on the data or port, root-owned files after sudo, a data directory from another MySQL version, a full disk, a bad my.cnf, or a mysqld that cannot load.

• psql: FATAL: password authentication failed for user "postgres" on a Mac

  A default Homebrew Postgres accepts any password from your Mac, so the error usually comes from a container: read the DETAIL line in its log, reset the password with docker exec when POSTGRES_PASSWORD was ignored, and check PGPASSWORD, ~/.pgpass and URL encoding.

• FATAL: lock file "postmaster.pid" already exists with Postgres on a Mac

  Postgres clears a dead pid file by itself, so this error means the PID is alive: check it with ps, stop the second server if it is a Postgres, delete the file only if it is not, and what the pg_ctl another server might be running line really means.

• FATAL: sorry, too many clients already on a local Postgres

  Homebrew and Docker both start at max_connections = 100 with 3 slots kept for superusers: list who holds the rest in pg_stat_activity, terminate the idle ones, fix the hot-reload pool or parallel test runner that opened them, and raise the limit with ALTER SYSTEM or a Docker command flag.

• psql or redis-cli hangs with no error: a server suspended with Ctrl+Z

  A Postgres or Redis you ran in a terminal and paused with Ctrl+Z keeps its port, so a port check passes and every client waits: find it with ps by its T state, then fg and Ctrl+C in its tab, or kill -CONT and kill -INT from any other.

• brew services start fails with “Bootstrap failed: 5: Input/output error”

  launchd’s generic error hides the cause: check launchctl print for a job still loaded from a crashed start and use brew services restart, read the service log for the real error, check the plist’s permissions and program path, and undo a sudo copy in /Library/LaunchDaemons.

Something missing? Email [email protected] with the error you hit.