See this dedicated page.
The following list contains all errors which may occur while you’re using Postgres.app.
Postgres.app includes the PostgreSQL binaries inside the application package. Each version is available bundled with either a single or all currently supported versions of PostgreSQL.
This error means that the binaries for this server are not included in the installed bundle. If the required version is still supported, you can download a different bundle from this page. If the version is no longer supported, you can find the last release supporting that version under legacy downloads. Please note that these releases are no longer maintained and you should migrate your data to a new version as soon as possible.
After the first start of Postgres.app, it is possible to alter the available versions of
PostgreSQL by copying the wanted versions out of the application package of other releases
to the directory /Applications/Postgres.app/Contents/Versions/
.
This error usually means that you already have a PostgreSQL server running on your Mac. If that is running within Postgres.app, expand the sidebar and stop that other server or alter the ‘Port’ under the button ‘Database Settings’.
If there isn’t an other server running within Postgres.app, you likely have a different installation of PostgreSQL running on your machine. To uninstall this, see the instructions on this page
It can also happen when a different user on your Mac is already running Postgres.app. Only a single server can run on each port.
If you want to use multiple PostgreSQL servers simultaneously, configure them to use a different port.
This can happen if you’ve configured Postgres.app to use a data directory that is used by a different PostgreSQL installation. Stop the other server before starting Postgres.app. In general, it is not recommended to just use a data directory created by another version of PostgreSQL, since it might have been configured differently.
PostgreSQL puts a file named postmaster.pid
in the data directory to store the process id of the PostgreSQL server process.
If PostgreSQL crashes, this file can contain an old pid that confuses PostgreSQL.
You can fix this issue by deleting the postmaster.pid
file. However, you must make sure that PostgreSQL is really not running.
Open Activity Monitor and make sure that there are no processes named ‘postgres’ or ‘postmaster’.
If you delete the postmaster.pid
file while PostgreSQL is running, bad things will happen.
This error means that the initdb
command failed.
This should not happen. If it does, please open an issue on Github.
For troubleshooting, try executing the following command manually:
/Applications/Postgres.app/Contents/Versions/latest/bin/initdb -D "DATA DIRECTORY" -U postgres --encoding=UTF-8 --locale=en_US.UTF-8
After the data directory is initialized, Postgres.app creates a default user and database. This error means that creating the user has failed. Check the server log (inside the data directory) for details.
You can try creating a default user and database manually:
/Applications/Postgres.app/Contents/Versions/latest/bin/createuser -U postgres -p PORT --superuser USERNAME
/Applications/Postgres.app/Contents/Versions/latest/bin/createdb -U USERNAME -p PORT DATABASENAME
Postgres.app uses your system user name for USERNAME and DATABASENAME by default.
Data directories and all its contents are only created when you start a server the first time. This error occurs when you attempt to open a data directory (or file) which doesn’t exist yet. Start the server first and try again.
This error should not occur. Please open an issue on Github and provide a detailed description what lead to this error.
The server log is inside the data directory in a file named postgres-server.log
.
Here are some errors that could appear:
Usually this error is caused by broken /etc/hosts
file.
The problem could be a missing localhost
entry, syntax errors or incorrect whitespace.
For reference, here is what this file should look like by default on macOS:
##
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting. Do not change this entry.
##
127.0.0.1 localhost
255.255.255.255 broadcasthost
::1 localhost
This error usually happens when you try to start a server that was initialized with a prerelease version of PostgreSQL. The on disk data format sometimes changes between pre-release versions. You need to start the server with the version you initialized it with, then dump the database, then create a new server with the new version and restore.
By default, Postgres.app creates a PostgreSQL user with the same user as your system user name. When this error occurs, it means that this user does not exist. You can create it by executing the following command in the Terminal:
createuser -U postgres -s $USER
-U postgres
tells createuser to connect with the postgres
user name-s
tells createuser to create a super user$USER
is a variable containing your system user name, and tells createuser the name of the postgres user you want to createBy default, psql tries to connect to a database with the same name as your local user. This error means that this database does not exist. This can have several possible reasons:
There are multiple ways to fix this problem:
createdb $USER
, orpsql postgres
to connect to the other default databaseUsually this error is caused by broken /etc/hosts
file.
The problem could be a missing localhost
entry, syntax errors or incorrect whitespace.
For reference, here is what this file should look like by default on macOS:
##
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting. Do not change this entry.
##
127.0.0.1 localhost
255.255.255.255 broadcasthost
::1 localhost
This error can occur when you delete the data directory while the PostgreSQL server is still running. To fix it, kill all PostgreSQL processes or restart your computer. Then start a new PostgreSQL server.
See this dedicated page.
See this dedicated page
For debugging, it is often useful to try starting the server manually:
/Applications/Postgres.app/Contents/Versions/latest/bin/postgres -D "DATA DIRECTORY" -p PORT
(replace DATA DIRECTORY with your data directory, make sure to include the quotes because the path might contain spaces)If you somehow mess up your Postgres.app installation, here’s how to start fresh.
CAUTION: This will delete all your databases, tables and data!
postgres
are running. If so, kill them. Kill the process with the lowest pid first; child processes are respawned automatically after killing them.~/Library/Application Support/Postgres
defaults delete com.postgresapp.Postgres2
If you run into any issues using Postgres.app, your first stop should be the issue tracker on Github.
If you encounter an issue and find a way to fix it, consider contributing to this documentation. This page is hosted on Github.