Database Errors

Can't Connect to PostgreSQL Docker Container#

When connecting your Medusa application to a PostgreSQL Docker container, make sure the 5432 port is exposed.

To do that, either pass the -p option to the docker run command. For example:

Terminal
❯docker run -d -p 5432:5432 --name some-postgres -e POSTGRES_PASSWORD=supersecret postgres

Or, if you're using Docker Desktop, you can provide the option under the container's "Optional settings" collapsable.

If you expose the PostgreSQL docker container at a port other than 5432, make sure to include it in your database URL.

When installing Medusa with create-medusa-app, you can provide a database URL with the different port using the --db-url option.

For example:

Terminal
❯npx create-medusa-app@latest --db-url "postgres://user:password@localhost:<YOUR_PORT>/medusa-store"

Where <YOUR_PORT> is the exposed port if it's different than 5432.

Refer to the databaseUrl configuration documentation to learn how to set the database URL for an installed Medusa application.

Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: Client password must be a string#

You may get the following error while running medusa new:

Terminal
❯Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a string

If the error occurs while running medusa new and you've selected to enter your database credentials, either:

1. Make sure your database credentials are correct;
2. Or choose the Skip option to skip entering your database credentials.

If the error occurs while running integration tests, make sure the following variable is set in your system's environment variable:

Terminal
❯DB_HOST=<YOUR_DB_HOST>❯DB_USERNAME=<YOUR_DB_USERNAME>❯DB_PASSWORD=<YOUR_PASSWORD>

Error: connect ECONNREFUSED ::1:5432#

When you start your Medusa application you may run into the following error:

Terminal
❯Error: connect ECONNREFUSED ::1:5432

This error occurs because the application couldn't connect to the PostgreSQL database. The issue could be one of the following:

1. PostgreSQL server isn't running. Make sure it's always running while the Medusa application is running.
2. The connection URL to your PostgreSQL database is incorrect. This could be because of incorrect credentials, port number, or connection URL format. The format should be postgres://[user][:password]@[host][:port]/[dbname]. Make sure that the connection URL format is correct, and the credentials passed in the URL are correct. You can learn more about formatting the connection URL here

Database User Privileges#

The database user you use in the databaseUrl Medusa backend configuration must have create privileges. Otherwise, you'll face problems when running migrations.

If you're using the postgres superuser, then it should have these privileges by default. Otherwise, make sure to grant your user create privileges. You can learn how to do that in PostgreSQL's documentation.