docs: added troubleshooting component (#4255)

docs/content/development/backend/install.mdx

@@ -6,6 +6,10 @@ addHowToData: true
 import Feedback from '@site/src/components/Feedback';
 import DocCardList from '@theme/DocCardList';
 import Icons from '@theme/Icon';
+import Troubleshooting from '@site/src/components/Troubleshooting'
+import SaslSection from '../../troubleshooting/database-errors/_sasl.md'
+import ConnectionErrorSection from '../../troubleshooting/database-errors/_connection-error.md'
+import FreshInstallationSection from '../../troubleshooting/awilix-resolution-error/_fresh-installation.md'
 
 # Install Medusa Backend
 
@@ -68,6 +72,12 @@ Make sure your PostgreSQL server is running before you run the Medusa backend.
    medusa develop
    ```
 
+After these three steps and in only a couple of minutes, you now have a complete commerce engine running locally. You can test it out by sending a request using a tool like Postman or through the command line:
+
+```bash noReport
+curl localhost:9000/store/products
+```
+
 <Feedback 
    event="survey_server_quickstart"
    question="Did you set up the backend successfully?"
@@ -75,7 +85,30 @@ Make sure your PostgreSQL server is running before you run the Medusa backend.
    negativeQuestion="Please describe the issue you faced."
 />
 
-### Seed Data 
+---
+
+## Troubleshooting Installation
+
+<Troubleshooting
+  sections={[
+    {
+      title: 'Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: Client password must be a string',
+      content: <SaslSection />
+    },
+    {
+      title: 'Error: connect ECONNREFUSED ::1:5432',
+      content: <ConnectionErrorSection />
+    },
+    {
+      title: 'AwilixResolutionError: Could Not Resolve X',
+      content: <FreshInstallationSection />
+    },
+  ]}
+/>
+
+---
+
+## Seed Data 
 
 For better testing, you can add demo data to your Medusa backend by running the seed command in your Medusa backend directory:
 
@@ -83,15 +116,9 @@ For better testing, you can add demo data to your Medusa backend by running the
 medusa seed --seed-file=data/seed.json
 ```
 
-### Test the Backend
+---
 
-After these three steps and in only a couple of minutes, you now have a complete commerce engine running locally. You can test it out by sending a request using a tool like Postman or through the command line:
-
-```bash noReport
-curl localhost:9000/store/products
-```
-
-### Health Route
+## Health Route
 
 You can access `/health` to get health status of your backend.
 

docs/content/development/backend/prepare-environment.mdx

@@ -4,6 +4,7 @@ description: 'Learn how to prepare your development environment while using Medu
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import MedusaCliTroubleshootingSection from '../../troubleshooting/cli-installation-errors/_reusable-section.mdx'
 
 # Prepare Development Environment
 
@@ -136,11 +137,9 @@ You can check that Medusa was installed by running the following command:
 medusa -v
 ```
 
-:::note
+#### Troubleshooting Installation
 
-If you run into any errors while installing the CLI tool, check out the [troubleshooting guide](../../troubleshooting/cli-installation-errors.mdx).
-
-:::
+<MedusaCliTroubleshootingSection />
 
 ### PostgreSQL
 

docs/content/development/endpoints/add-middleware.mdx

@@ -3,6 +3,10 @@ description: 'Learn how to add a middleware in Medusa. A middleware is a functio
 addHowToData: true
 ---
 
+import Troubleshooting from '@site/src/components/Troubleshooting'
+import ServiceLifetimeSection from '../../troubleshooting/awilix-resolution-error/_service-lifetime.md'
+import CustomRegistrationSection from '../../troubleshooting/awilix-resolution-error/_custom-registration.md'
+
 # Middlewares
 
 In this document, you’ll learn how to add a middleware to an existing or custom route in Medusa.
@@ -103,7 +107,7 @@ In some cases, you may need to register a resource to use within your commerce a
 
 :::tip
 
-If you want to register a logged-in user and access it in your resources, you can check out [this example guide](./example-logged-in-user.md).
+If you want to register a logged-in user and access it in your resources, you can check out [this example guide](./example-logged-in-user.mdx).
 
 :::
 
@@ -151,7 +155,7 @@ Notice that you have to wrap your usage of the new resource in a try-catch block
 
 ### Note About Services Lifetime
 
-If you want to access new registrations in the dependency container within a service, you must set the lifetime of the service either to `Lifetime.SCOPED` or `Lifetime.TRANSIENT`.  Services that have a `Lifetime.SINGLETON` lifetime can't access new registrations since they're resolved and cached in the root dependency container beforehand. You can learn more in the [Create Services documentation](../services/create-service.md#service-life-time).
+If you want to access new registrations in the dependency container within a service, you must set the lifetime of the service either to `Lifetime.SCOPED` or `Lifetime.TRANSIENT`.  Services that have a `Lifetime.SINGLETON` lifetime can't access new registrations since they're resolved and cached in the root dependency container beforehand. You can learn more in the [Create Services documentation](../services/create-service.mdx#service-life-time).
 
 For custom services, no additional action is required as the default lifetime is `Lifetime.SCOPED`. However, if you extend a core service, you must change the lifetime since the default lifetime for core services is `Lifetime.SINGLETON`.
 
@@ -189,6 +193,23 @@ export default ProductService
 
 ---
 
+## Troubleshooting
+
+<Troubleshooting 
+  sections={[
+    {
+      title: 'AwilixResolutionError: Could Not Resolve X',
+      content: <ServiceLifetimeSection />
+    },
+    {
+      title: 'AwilixResolutionError: Could Not Resolve X (Custom Registration)',
+      content: <CustomRegistrationSection />
+    }
+  ]}
+/>
+
+---
+
 ## See Also
 
 - [Store API reference](/api/store)

docs/content/development/endpoints/create.md

@@ -42,7 +42,7 @@ This exports a function that returns an Express router. The function receives tw
 
 ### Defining Multiple Routes or Middlewares
 
-Instead of returning an Express router in the function, you can return an array of routes and [middlewares](./add-middleware.md).
+Instead of returning an Express router in the function, you can return an array of routes and [middlewares](./add-middleware.mdx).
 
 For example:
 

docs/content/development/endpoints/example-logged-in-user.mdx

@@ -3,13 +3,17 @@ description: 'In this document, you’ll see an example of how you can use middl
 addHowToData: true
 ---
 
+import Troubleshooting from '@site/src/components/Troubleshooting'
+import ServiceLifetimeSection from '../../troubleshooting/awilix-resolution-error/_service-lifetime.md'
+import CustomRegistrationSection from '../../troubleshooting/awilix-resolution-error/_custom-registration.md'
+
 # Example: Access Logged-In User
 
 In this document, you’ll see an example of how you can use middlewares and endpoints to register the logged-in user in the dependency container of your commerce application. You can then access the logged-in user in other resources, such as services.
 
 This guide showcases how to register the logged-in admin user, but you can apply the same steps if you want to register the current customer.
 
-This documentation does not explain the basics of [middlewares](./add-middleware.md) and [endpoints](./create.md). You can refer to their respective guides for more details about each.
+This documentation does not explain the basics of [middlewares](./add-middleware.mdx) and [endpoints](./create.md). You can refer to their respective guides for more details about each.
 
 ## Step 1: Create the Middleware
 
@@ -178,7 +182,7 @@ class ProductService extends MedusaProductService {
 export default ProductService
 ```
 
-You can learn more about the importance of changing the service lifetime in the [Middlewares documentation](./add-middleware.md#note-about-services-lifetime).
+You can learn more about the importance of changing the service lifetime in the [Middlewares documentation](./add-middleware.mdx#note-about-services-lifetime).
 
 ---
 
@@ -197,3 +201,20 @@ npx @medusajs/medusa-cli develop
 ```
 
 If you try accessing the endpoints you added the middleware to, you should see your implementation working as expected.
+
+---
+
+## Troubleshooting
+
+<Troubleshooting 
+  sections={[
+    {
+      title: 'AwilixResolutionError: Could Not Resolve X',
+      content: <ServiceLifetimeSection />
+    },
+    {
+      title: 'AwilixResolutionError: Could Not Resolve X (Custom Registration)',
+      content: <CustomRegistrationSection />
+    }
+  ]}
+/>

docs/content/development/entities/migrations/overview.mdx

@@ -59,7 +59,7 @@ npx @medusajs/medusa-cli@latest migrations revert
 
 ### Other Migrations Commands
 
-You can learn about migration commands available in the Medusa CLI tool by referring to the [Medusa CLI reference](../../../cli/reference.md#migrations)
+You can learn about migration commands available in the Medusa CLI tool by referring to the [Medusa CLI reference](../../../cli/reference.mdx#migrations)
 
 ---
 

docs/content/development/feature-flags/toggle.md

@@ -80,4 +80,4 @@ Once you disable a feature flag, all endpoints, entities, services, or other rel
 
 If you had the feature flag previously enabled, and you want to disable this feature flag completely, you might need to revert the migrations you ran when you enabled it.
 
-You can follow [this documentation to learn how to revert the last migration you ran](../../cli/reference.md#migrations).
+You can follow [this documentation to learn how to revert the last migration you ran](../../cli/reference.mdx#migrations).

docs/content/development/file-service/overview.mdx

@@ -13,7 +13,7 @@ In this document, you’ll learn what a file service is in Medusa.
 
 A file service defines how files are stored in the Medusa Backend. Those files include products’ images and files used to import or export data.
 
-Medusa Backend includes a default file service that acts as a placeholder, but does not actually perform any storage functionalities. So, you must either install one of the [existing file-service plugins](../../plugins/file-service/index.mdx), such as [MinIO](../../plugins/file-service/minio.md) or [S3](../../plugins/file-service/s3.md), or create your own file service if you want to utilize storage functionalities.
+Medusa Backend includes a default file service that acts as a placeholder, but does not actually perform any storage functionalities. So, you must either install one of the [existing file-service plugins](../../plugins/file-service/index.mdx), such as [MinIO](../../plugins/file-service/minio.md) or [S3](../../plugins/file-service/s3.mdx), or create your own file service if you want to utilize storage functionalities.
 
 A file service is a TypeScript or JavaScript class that extends the `AbstractFileService` class from the core `@medusajs/medusa` package. By extending this class, the file service must implement the necessary methods that take care of general upload and download functionalities. The Medusa Backend then uses these methods when necessary, for example, when a product image is uploaded.
 

docs/content/development/fundamentals/dependency-injection.md

@@ -38,7 +38,7 @@ The Medusa backend scans the core Medusa package, plugins, and your files in the
 
 :::tip
 
-The Lifetime column indicates the lifetime of a service. Other resources that aren't services don't have a lifetime, which is indicated with the `-` in the column. You can learn about what a lifetime is in the [Create a Service](../services/create-service.md) documentation.
+The Lifetime column indicates the lifetime of a service. Other resources that aren't services don't have a lifetime, which is indicated with the `-` in the column. You can learn about what a lifetime is in the [Create a Service](../services/create-service.mdx) documentation.
 
 :::
 
@@ -731,5 +731,5 @@ class OrderSubscriber {
 
 ## See Also
 
-- [Create services](../services/create-service.md)
+- [Create services](../services/create-service.mdx)
 - [Create subscribers](../events/create-subscriber.md)

docs/content/development/notification/create-notification-provider.md

@@ -67,7 +67,7 @@ Notification Providers must extend `NotificationService` from `medusa-interfa
 
 :::info
 
-Following the naming convention of Services, the name of the file should be the slug name of the Notification Provider, and the name of the class should be the camel case name of the Notification Provider suffixed with “Service”. In the example above, the name of the file should be `email-sender.js`. You can learn more in the [service documentation](../services/create-service.md).
+Following the naming convention of Services, the name of the file should be the slug name of the Notification Provider, and the name of the class should be the camel case name of the Notification Provider suffixed with “Service”. In the example above, the name of the file should be `email-sender.js`. You can learn more in the [service documentation](../services/create-service.mdx).
 
 :::
 

docs/content/development/notification/overview.mdx

@@ -25,7 +25,7 @@ An example of a notification provider is SendGrid. When an order is placed, the
 
 ### How Notification Provider is Created
 
-A Notification Provider is essentially a Medusa [Service](../services/create-service.md) with a unique identifier, and it extends the [`NotificationService`](../../references/services/classes/NotificationService.md) provided by the `medusa-interfaces` package. It can be created as part of a [Plugin](../plugins/overview.mdx), or it can be created just as a Service file in your Medusa backend.
+A Notification Provider is essentially a Medusa [Service](../services/create-service.mdx) with a unique identifier, and it extends the [`NotificationService`](../../references/services/classes/NotificationService.md) provided by the `medusa-interfaces` package. It can be created as part of a [Plugin](../plugins/overview.mdx), or it can be created just as a Service file in your Medusa backend.
 
 As a developer, you mainly work with the Notification Provider when integrating a third-party service that handles notifications in Medusa.
 

docs/content/development/plugins/create.md

@@ -136,7 +136,7 @@ It was previously required to output your files into the root of the plugin's di
 This guide doesn't cover how to create different files and components. If you’re interested in learning how to do that, you can check out these guides:
 
 - How to [create endpoints](../endpoints/create.md)
-- How to [create a service](../services/create-service.md)
+- How to [create a service](../services/create-service.mdx)
 - How to [create a subscriber](../events/create-subscriber.md)
 - How to [create an entity](../entities/create.md)
 - How to [create a migration](../entities/migrations/create.md)

docs/content/development/search/overview.mdx

@@ -15,7 +15,7 @@ A search service is used to manage search indices of searchable items, such as p
 
 A search service is a service class that is defined in a TypeScript or JavaScript file, which is created in the `src/services` directory of your Medusa backend codebase or plugin. The class must extend the `AbstractSearchService` class imported from the `@medusajs/utils` package.
 
-Using the [dependency container and injection](../fundamentals/dependency-injection.md), the Medusa backend will then use and resolve the search service within the backend’s search operations, such as when the [Search Product](/api/store#tag/Products/operation/PostProductsSearch) endpoint is used. You can also [resolve the service](../services/create-service.md#use-a-service) within your resources to trigger the search where necessary.
+Using the [dependency container and injection](../fundamentals/dependency-injection.md), the Medusa backend will then use and resolve the search service within the backend’s search operations, such as when the [Search Product](/api/store#tag/Products/operation/PostProductsSearch) endpoint is used. You can also [resolve the service](../services/create-service.mdx#use-a-service) within your resources to trigger the search where necessary.
 
 Medusa provides official plugins that you can install and use in your Medusa backend. Check out available search plugins [here](../../plugins/search/index.mdx).
 

docs/content/development/services/create-service.mdx

@@ -3,6 +3,9 @@ description: 'Learn how to create a service in Medusa. This guide also includes
 addHowToData: true
 ---
 
+import Troubleshooting from '@site/src/components/Troubleshooting'
+import ServiceLifetimeSection from '../../troubleshooting/awilix-resolution-error/_service-lifetime.md'
+
 # How to Create a Service
 
 In this document, you’ll learn how you can create a [Service](./overview.mdx) and use it across your Medusa backend just like any of the core services.
@@ -143,6 +146,19 @@ class MySubscriber {
 
 ---
 
+## Troubleshooting
+
+<Troubleshooting 
+  sections={[
+    {
+      title: 'AwilixResolutionError: Could Not Resolve X',
+      content: <ServiceLifetimeSection />
+    }
+  ]}
+/>
+
+---
+
 ## See Also
 
 - [Create a Plugin](../plugins/create.md)

docs/content/development/services/extend-service.mdx

@@ -3,6 +3,9 @@ description: 'Learn how to create a service in Medusa. This guide also includes
 addHowToData: true
 ---
 
+import Troubleshooting from '@site/src/components/Troubleshooting'
+import ServiceLifetimeSection from '../../troubleshooting/awilix-resolution-error/_service-lifetime.md'
+
 # How to Extend a Service
 
 In this document, you’ll learn how to extend a core service in Medusa.
@@ -65,7 +68,7 @@ class ProductService extends MedusaProductService {
 export default ProductService
 ```
 
-You can learn more details about the service lifetime and other considerations when creating a service in the [Create Service documentation](./create-service.md).
+You can learn more details about the service lifetime and other considerations when creating a service in the [Create Service documentation](./create-service.mdx).
 
 ---
 
@@ -84,3 +87,16 @@ npx @medusajs/medusa-cli develop
 ```
 
 You should see the customizations you made in effect.
+
+---
+
+## Troubleshooting
+
+<Troubleshooting 
+  sections={[
+    {
+      title: 'AwilixResolutionError: Could Not Resolve X (Service Lifetime)',
+      content: <ServiceLifetimeSection />
+    }
+  ]}
+/>