Common create-medusa-app Errors

TypeError: cmd is not a function#

This error typically occurs when you set up a Medusa project with create-medusa-app and try to run the Medusa application.

To resolve this issue, make sure you change into the application's directory of the Medusa project you created before trying to start the Medusa application:

npm
yarn
pnpm

Errors when using VSCode or GitHub Codespaces#

If you're running the Medusa application through tools like VSCode or GitHub Codespaces, you must ensure that:

1. Port forwarding is configured for ports 9000 and 7001. Refer to the following resources on how to configure forwarded ports:
   • VSCode local development.
   • VSCode remote development.
   • GitHub Codespaces.
2. If your tool or IDE exposes an address other than localhost, such as 127.0.0.1, make sure to add that address to the adminCors Medusa configuration. Your tool will show you what the forwarded address is.

After setting these configurations, run your Medusa application and try again. If you couldn't create an admin user before, run the following command in the root directory of your Medusa project to create an admin user:

Terminal
❯npx medusa user -e admin@medusa-test.com -p supersecret

Invalid Token Error with --no-browser Option#

If you use the --no-browser option with the create-medusa-app command, you'll find a URL outputted at the end of the command execution. This is the URL that you can use to set a password for your admin user.

However, if you copy the URL, then try later to access that URL, you may receive an "Invalid Token" error. This is because when you copy the URL, a lot of extra space may be added into the token. So, you must clear out the spaces within the token and the || characters, then try again.

Alternatively, you can create a new user with the medusa user command.

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.

Can't connect to database with --db-url option#

If you use the --db-url option with the create-medusa-app command and the connection to the database fails, try the following:

• Specify ?sslmode=require at the end of the connection URL. Some PostgreSQL hosting providers, like Vercel, require passing this option. For example:

Terminal
❯npx create-medusa-app@latest --db-url "postgres://default:<password><host-region>.postgres.vercel-storage.com:5432/verceldb?sslmode=require"

• Change the password to remove special characters. PostgreSQL requires encoding passwords if they have special characters. While the create-medusa-app command handles this automatically when you specify the password to the create-medusa-app command, when you pass a connection URL with the --db-url the command uses that URL as-is. So, you must either encode the special characters in the password yourself, or remove the special characters in the password.

Can't Access Next.js Starter Storefront#

By default, passing the --with-nextjs-starter to the create-medusa-app command starts both the Medusa application at localhost:9000 and the Next.js Starter storefront at localhost:8000 once the installation finishes successfully. The Medusa Admin also opens in your default browser.

If, while following along the setup process, you try to access the Next.js Starter Storefront and it's not working, try to run the storefront manually while the Medusa application is still running.

To do that, first, change to the directory of the storefront. The directory name is {project_name}-storefront, where {project_name} is the name you chose for the project while running the create-medusa-app command. For example:

Terminal
❯cd my-medusa-store-storefront

Then, run the following command to start the storefront:

npm
yarn
pnpm

The storefront runs on localhost:8000 now.

Other Errors#

As a last resort to resolve your issue, please try to clear your npx cache, as it could hold a cached version of create-medusa-app with errors.

Terminal
❯rm -rf "$(npm config get cache)/_npx"

If your issue persists, please try to search through our GitHub issues to see if there's a solution for your issue. If not, please create an issue on GitHub and our team will help you resolve it soon."