docs: triage issues + revamp troubleshooting guides (#14216)

* docs: triage issues + revamp troubleshooting guides * small change
2025-12-04 17:12:48 +02:00
1 parent a00bba5cfc
commit e3e3c725db
@@ -1,18 +1,26 @@
-You may get the following error while running `medusa new`:
+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:

 ```bash
+Error: connect ECONNREFUSED ::1:5432
 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:
+### Error During Installation

-1. Make sure your database credentials are correct;
-2. Or choose the Skip option to skip entering your database credentials.
+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:

-If the error occurs while running integration tests, make sure the following variable is set in your system's environment variable:
+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.

-```bash
-DB_HOST=<YOUR_DB_HOST>
-DB_USERNAME=<YOUR_DB_USERNAME>
-DB_PASSWORD=<YOUR_PASSWORD>
-```
+### 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](!docs!/learn/configurations/medusa-config#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.
@@ -5,6 +5,8 @@ import InvalidTokenError from "../_sections/create-medusa-app-errors/no-browser-
 import DockerSection from "../_sections/database-errors/docker.mdx"
 import DbUrlError from "../_sections/create-medusa-app-errors/db-url-error.mdx"
 import ForwardingError from "../_sections/create-medusa-app-errors/forwarding.mdx"
+import SaslSection from '../_sections/database-errors/sasl.mdx'
+import ModuleXErrorSection from '../_sections/common-installation-errors/module-x-error.mdx'

 export const metadata = {
  title: `Common create-medusa-app Errors`,
@@ -12,6 +14,14 @@ export const metadata = {

 # {metadata.title}

+This troubleshooting guide covers common errors you may encounter when using the `create-medusa-app` command to set up a new Medusa application and how to resolve them.
+
+## General Errors Connecting to Database
+
+<SaslSection />
+
+---
+
 ## TypeError: cmd is not a function

 <TypeError />
@@ -48,6 +58,12 @@ export const metadata = {

 ---

+## Resolve "Cannot find module X" Errors
+
+<ModuleXErrorSection />
+
+---
+
 ## Other Errors

 <OtherErrors />
@@ -1,6 +1,5 @@
 import SaslSection from '../_sections/database-errors/sasl.mdx'
 import ConnectionErrorSection from '../_sections/database-errors/connection-error.mdx'
-import PrivilegesSection from '../_sections/database-errors/privileges.mdx'
 import DockerSection from "../_sections/database-errors/docker.mdx"

 export const metadata = {
@@ -9,24 +8,14 @@ export const metadata = {

 # {metadata.title}

-## Can't Connect to PostgreSQL Docker Container
+This troubleshooting guide covers common database errors you may encounter when working with Medusa and how to resolve them.

-<DockerSection />
-
---
-
-## Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: Client password must be a string
+## General Errors Connecting to Database

 <SaslSection />

 ---

-## Error: connect ECONNREFUSED ::1:5432
+## Can't Connect to PostgreSQL Docker Container

-<ConnectionErrorSection />
-
---
-
-## Database User Privileges
-
-<PrivilegesSection />
+<DockerSection />
@@ -1,15 +1,19 @@
 export const metadata = {
-  title: `Errors After Upgrading`,
+  title: `Errors After Upgrading Medusa`,
 }

 # {metadata.title}

-If you run into errors after updating Medusa and its dependencies, it's highly recommended to check the Upgrade Guides if there is a specific guide for your version. These guides include steps required to perform after upgrading Medusa.
+If you run into errors after updating your Medusa application, it's highly recommended to check the [GitHub Release Notes](https://github.com/medusajs/medusa/releases) for any upgrade guides related to the version you upgraded to. These release notes may include details on breaking changes and how to resolve them before upgrading.

-If there's no upgrade guide for your version, make sure that you ran the `db:migrate` command in the root directory of your Medusa application:
+Also, after updating your Medusa application, make sure that you ran the `db:migrate` command in the root directory of your Medusa application:

 ```bash
 npx medusa db:migrate
 ```

 This ensures your application has the latest database structure required. Then, try running your Medusa application again and check whether the same error occurs.
+
+## Additional Resources
+
+- [Updating Medusa](!docs!/learn/update)
@@ -8,7 +8,7 @@ export const metadata = {

 # {metadata.title}

-In this document, you can find solutions to some common problems that occur when installing Medusa’s CLI Tool.
+This troubleshooting guide covers common errors you may encounter when installing the Medusa CLI and how to resolve them.

 ## NPM Error: EACCES Permissions Errors

@@ -6,6 +6,8 @@ export const metadata = {

 # {metadata.title}

+This troubleshooting guide covers general errors you may encounter while installing or developing with Medusa and how to resolve them.
+
 ## Resolve "Cannot find module X" Errors

 <ModuleXErrorSection />
@@ -4,7 +4,7 @@ export const metadata = {

 # {metadata.title}

-This guide provides some troubleshooting step as to why your admin widget / UI route isn't showing in the Medusa Admin dashboard.
+This troubleshooting guide covers common reasons why an admin widget or UI route may not be showing in your Medusa Admin and how to resolve them.

 ## Incorrect Zone

@@ -6,6 +6,8 @@ export const metadata = {

 # {metadata.title}

+This troubleshooting guide covers common errors you may encounter when using payment providers in your Medusa application and how to resolve them.
+
 ## Unknown Error for Zero Cart Total

 <ZeroTotalError />
@@ -2,11 +2,13 @@ import S3BucketAcl from "../_sections/s3/aws-bucket-acl.mdx"
 import CloudflareChecksum from "../_sections/s3/cloudflare-checksum.mdx"

 export const metadata = {
-  title: `S3 Module Provider Errors`,
+  title: `S3 File Module Provider Errors`,
 }

 # {metadata.title}

+This troubleshooting guide covers common errors you may encounter when using the [S3 File Module Provider](../../infrastructure-modules/file/s3/page.mdx) in your Medusa application and how to resolve them.
+
 ## AWS: The bucket does not allow ACLs

 <S3BucketAcl />
@@ -7,7 +7,7 @@ export const metadata = {

 # {metadata.title}

-This guide helps you troubleshoot issues when a scheduled job in your Medusa application is not running, or running at unexpected times.
+This troubleshooting guide helps you troubleshoot issues when a scheduled job in your Medusa application is not running, or running at unexpected times.

 ## Confirm Job is Set Up Correctly

@@ -7,7 +7,7 @@ export const metadata = {

 # {metadata.title}

-This guide helps you troubleshoot issues when subscribers in your Medusa application are not running.
+This troubleshooting guide helps you troubleshoot issues when subscribers in your Medusa application are not running.

 ## Confirm Event is Emitted

@@ -1,9 +1,11 @@
 export const metadata = {
-  title: `Test Errors`,
+  title: `Errors When Running Tests`,
 }

 # {metadata.title}

+This troubleshooting guide covers common errors you may encounter when running tests in your Medusa application and how to resolve them.
+
 ## Loaders for module Workflows failed

 If you get the following error when running your tests:
@@ -23,10 +25,16 @@ module.exports = {

 Then, create the `integration-tests/setup.js` file with the following content:

+<Note>
+
+If you're using a version prior to Medusa v2.11.0, change `@medusajs/framework/mikro-orm/core` to `@mikro-orm/core`. Learn more in the [v2.11.0 codemod](!docs!/learn/codemods/replace-imports).
+
+</Note>
+
 ```js title="integration-tests/setup.js"
 const { MetadataStorage } = require("@medusajs/framework/mikro-orm/core")

 MetadataStorage.clear()
 ```

-Learn more about configuring test tools in [this documentation](!docs!/learn/debugging-and-testing/testing-tools)
+Refer to the [Testing Tools](!docs!/learn/debugging-and-testing/testing-tools) guide for more details.