Database Errors

This troubleshooting guide covers common database errors you may encounter when working with Medusa and how to resolve them.

General Errors Connecting to Database#

When installing or running Medusa, you may get errors while Medusa tries to connect to your PostgreSQL database.

For example, you may get one of the following errors:

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

Error During Installation#

If the connectivity error occurs while running create-medusa-app, it means you passed incorrect database credentials when prompted during the installation. Make sure that:

1. PostgreSQL is installed and running on your machine;
2. Your PostgreSQL server is configured at localhost:5432 (the default host and port); If not, you can pass the --db-url <url> flag to the create-medusa-app command to specify a custom database URL;
3. You're passing correct username and password for your PostgreSQL database;
4. You're using a user that has privileges to create new databases;
5. You're passing correct database name for your PostgreSQL user. It should have the same name as your PostgreSQL user by default.

Error During Development#

If the error occurs while running integration tests, make sure that:

1. The DATABASE_URL environment variable is set correctly in your .env file;
2. The projectConfig.databaseUrl field in your medusa-config.js file is set to the DATABASE_URL environment variable;
3. The database URL is using correct username and password, and points to a running PostgreSQL database instance.

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:

yarn
pnpm
npx

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.