docs: added troubleshooting component (#4255)
This commit is contained in:
Shahed Nasser
@@ -1,78 +0,0 @@
|
||||
# AwilixResolutionError: Could Not Resolve X
|
||||
|
||||
This troubleshooting guide will help you figure out the different situations that can cause an `AwilixResolutionError`.
|
||||
|
||||
## Option 1: Service Lifetime
|
||||
|
||||
If you're registering a custom resource within a middleware, for example a logged-in user, then make sure that all services that are using it have their `LIFE_TIME` static property either set to `Lifetime.SCOPED` or `Lifetime.TRANSIENT`. This mainly applies for services in the core Medusa package, as, by default, their lifetime is `Lifetime.SINGLETON`.
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
import { Lifetime } from "awilix"
|
||||
import {
|
||||
ProductService as MedusaProductService,
|
||||
} from "@medusajs/medusa"
|
||||
|
||||
// extending ProductService from the core
|
||||
class ProductService extends MedusaProductService {
|
||||
// The default life time for a core service is SINGLETON
|
||||
static LIFE_TIME = Lifetime.SCOPED
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default ProductService
|
||||
```
|
||||
|
||||
This may require you to extend a service as explained in [this documentation](../development/services/extend-service.md) if necessary.
|
||||
|
||||
If you're unsure which service you need to change its `LIFE_TIME` property, it should be mentioned along with the `AwilixResolutionError` message. For example:
|
||||
|
||||
```bash noCopy noReport
|
||||
AwilixResolutionError: Could not resolve 'loggedInUser'.
|
||||
|
||||
Resolution path: cartService -> productService -> loggedInUser
|
||||
```
|
||||
|
||||
As shown in the resolution path, you must change the `LIFE_TIME` property of both `cartService` and `productService` to `Lifetime.SCOPED` or `Lifetime.TRANSIENT`.
|
||||
|
||||
You can learn about the service lifetime in the [Create a Service documentation](../development/services/create-service.md).
|
||||
|
||||
## Option 2: Using Try-Catch Block with Custom Registration
|
||||
|
||||
When you register a custom resource using a middleware, make sure that when you use it in a service's constructor you wrap it in a try-catch block. This can cause an error when the Medusa backend first runs, especially if the service is used within a subscriber. Subscribers are built the first time the Medusa backend runs, meaning that their dependencies are registered at that point. Since your custom resource hasn't been registered at this point, it will cause an `AwilixResolutionError` when the backend tries to resolve it.
|
||||
|
||||
For that reason, and to avoid other similar situations, make sure to always wrap your custom resources in a try-catch block when you use them inside the constructor of a service. For example:
|
||||
|
||||
<!-- eslint-disable prefer-rest-params -->
|
||||
|
||||
```ts
|
||||
import { TransactionBaseService } from "@medusajs/medusa"
|
||||
|
||||
class CustomService extends TransactionBaseService {
|
||||
|
||||
constructor(container, options) {
|
||||
super(...arguments)
|
||||
|
||||
// use the registered resource.
|
||||
try {
|
||||
container.customResource
|
||||
} catch (e) {
|
||||
// avoid errors when the backend first loads
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export default CustomService
|
||||
```
|
||||
|
||||
You can learn more about this in the [Middlewares documentation](../development/endpoints/add-middleware.md).
|
||||
|
||||
## Option 3: Error on A Fresh Installation
|
||||
|
||||
If you get the error on a fresh installation of the Medusa backend, or you haven't made any customizations that would cause this error, try to remove the `node_modules` directory, then run the following command in the root directory of the Medusa backend to re-install the dependencies:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install
|
||||
```
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: 'AwilixResolutionError: Could Not Resolve X'
|
||||
---
|
||||
|
||||
import ServiceLifetimeSection from './awilix-resolution-error/_service-lifetime.md'
|
||||
import CustomRegistrationSection from './awilix-resolution-error/_custom-registration.md'
|
||||
import FreshInstallationSection from './awilix-resolution-error/_fresh-installation.md'
|
||||
|
||||
This troubleshooting guide will help you figure out the different situations that can cause an `AwilixResolutionError`.
|
||||
|
||||
## Option 1: Service Lifetime
|
||||
|
||||
<ServiceLifetimeSection />
|
||||
|
||||
---
|
||||
|
||||
## Option 2: Using Try-Catch Block with Custom Registration
|
||||
|
||||
<CustomRegistrationSection />
|
||||
|
||||
---
|
||||
|
||||
## Option 3: Error on A Fresh Installation
|
||||
|
||||
<FreshInstallationSection />
|
||||
@@ -0,0 +1,27 @@
|
||||
When you register a custom resource using a middleware, make sure that when you use it in a service's constructor you wrap it in a try-catch block. This can cause an error when the Medusa backend first runs, especially if the service is used within a subscriber. Subscribers are built the first time the Medusa backend runs, meaning that their dependencies are registered at that point. Since your custom resource hasn't been registered at this point, it will cause an `AwilixResolutionError` when the backend tries to resolve it.
|
||||
|
||||
For that reason, and to avoid other similar situations, make sure to always wrap your custom resources in a try-catch block when you use them inside the constructor of a service. For example:
|
||||
|
||||
<!-- eslint-disable prefer-rest-params -->
|
||||
|
||||
```ts
|
||||
import { TransactionBaseService } from "@medusajs/medusa"
|
||||
|
||||
class CustomService extends TransactionBaseService {
|
||||
|
||||
constructor(container, options) {
|
||||
super(...arguments)
|
||||
|
||||
// use the registered resource.
|
||||
try {
|
||||
container.customResource
|
||||
} catch (e) {
|
||||
// avoid errors when the backend first loads
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export default CustomService
|
||||
```
|
||||
|
||||
You can learn more about this in the [Middlewares documentation](../../development/endpoints/add-middleware.mdx).
|
||||
@@ -0,0 +1,5 @@
|
||||
If you get the error on a fresh installation of the Medusa backend, or you haven't made any customizations that would cause this error, try to remove the `node_modules` directory, then run the following command in the root directory of the Medusa backend to re-install the dependencies:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install
|
||||
```
|
||||
@@ -0,0 +1,34 @@
|
||||
If you're registering a custom resource within a middleware, for example a logged-in user, then make sure that all services that are using it have their `LIFE_TIME` static property either set to `Lifetime.SCOPED` or `Lifetime.TRANSIENT`. This mainly applies for services in the core Medusa package, as, by default, their lifetime is `Lifetime.SINGLETON`.
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
import { Lifetime } from "awilix"
|
||||
import {
|
||||
ProductService as MedusaProductService,
|
||||
} from "@medusajs/medusa"
|
||||
|
||||
// extending ProductService from the core
|
||||
class ProductService extends MedusaProductService {
|
||||
// The default life time for a core service is SINGLETON
|
||||
static LIFE_TIME = Lifetime.SCOPED
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default ProductService
|
||||
```
|
||||
|
||||
This may require you to extend a service as explained in [this documentation](../../development/services/extend-service.mdx) if necessary.
|
||||
|
||||
If you're unsure which service you need to change its `LIFE_TIME` property, it should be mentioned along with the `AwilixResolutionError` message. For example:
|
||||
|
||||
```bash noCopy noReport
|
||||
AwilixResolutionError: Could not resolve 'loggedInUser'.
|
||||
|
||||
Resolution path: cartService -> productService -> loggedInUser
|
||||
```
|
||||
|
||||
As shown in the resolution path, you must change the `LIFE_TIME` property of both `cartService` and `productService` to `Lifetime.SCOPED` or `Lifetime.TRANSIENT`.
|
||||
|
||||
You can learn about the service lifetime in the [Create a Service documentation](../../development/services/create-service.mdx).
|
||||
@@ -1,15 +1,16 @@
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
---
|
||||
title: 'Resolve Errors Installing Medusa CLI'
|
||||
---
|
||||
|
||||
# Resolve Errors Installing Medusa CLI
|
||||
import PermissionErrorsSection from './cli-installation-errors/_permission-errors.md'
|
||||
import PowershellErrorSection from './cli-installation-errors/_powershell-error.md'
|
||||
import YarnError from './cli-installation-errors/_yarn-error.mdx'
|
||||
|
||||
In this document, you can find solutions to some common problems that occur when installing Medusa’s CLI Tool.
|
||||
|
||||
## NPM Error: EACCES Permissions Errors
|
||||
|
||||
If you install the Medusa CLI tool with NPM and get a permission error, NPM proposes as a solution either re-installing NPM with a node version manager (nvm), or manually setting npm’s default directory.
|
||||
|
||||
You can check out more information in [NPM’s documentation](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally).
|
||||
<PermissionErrorsSection />
|
||||
|
||||
---
|
||||
|
||||
@@ -19,13 +20,7 @@ You can check out more information in [NPM’s documentation](https://docs.npmjs
|
||||
|
||||
<!-- vale on -->
|
||||
|
||||
If you're using Powershell and you installed the CLI tool, but when you try to use it you get the error:
|
||||
|
||||
```bash noReport
|
||||
command not found: medusa
|
||||
```
|
||||
|
||||
Try closing your Powershell window and opening a new one.
|
||||
<PowershellErrorSection />
|
||||
|
||||
---
|
||||
|
||||
@@ -35,31 +30,4 @@ Try closing your Powershell window and opening a new one.
|
||||
|
||||
<!-- vale on -->
|
||||
|
||||
If you install the Medusa CLI tool with Yarn, then try to use the CLI tool but get the error:
|
||||
|
||||
```bash noReport
|
||||
command not found: medusa
|
||||
```
|
||||
|
||||
You have to add Yarn’s install location to the PATH variable:
|
||||
|
||||
<Tabs groupId="operating-systems" isCodeTabs={true}>
|
||||
<TabItem value="unix" label="MacOS / Linux" default>
|
||||
|
||||
```bash
|
||||
export PATH="$(yarn global bin):$PATH"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="windows" label="Windows">
|
||||
|
||||
```bash
|
||||
# MAKE SURE TO INCLUDE %path%
|
||||
setx path "%path%;c:\users\YOURUSERNAME\appdata\local\yarn\bin"
|
||||
# YOURUSERNAME is your account username
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
You can learn more in [Yarn’s documentation](https://classic.yarnpkg.com/en/docs/cli/global#adding-the-install-location-to-your-path).
|
||||
<YarnError />
|
||||
@@ -0,0 +1,3 @@
|
||||
If you install the Medusa CLI tool with NPM and get a permission error, NPM proposes as a solution either re-installing NPM with a node version manager (nvm), or manually setting npm’s default directory.
|
||||
|
||||
You can check out more information in [NPM’s documentation](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally).
|
||||
@@ -0,0 +1,7 @@
|
||||
If you're using Powershell and you installed the CLI tool, but when you try to use it you get the error:
|
||||
|
||||
```bash noReport
|
||||
command not found: medusa
|
||||
```
|
||||
|
||||
Try closing your Powershell window and opening a new one.
|
||||
@@ -0,0 +1,21 @@
|
||||
import Troubleshooting from '@site/src/components/Troubleshooting'
|
||||
import PermissionErrorsSection from './_permission-errors.md'
|
||||
import PowershellErrorSection from './_powershell-error.md'
|
||||
import YarnErrorSection from './_yarn-error.mdx'
|
||||
|
||||
<Troubleshooting
|
||||
sections={[
|
||||
{
|
||||
title: "NPM Error: EACCES Permissions Errors",
|
||||
content: <PermissionErrorsSection />
|
||||
},
|
||||
{
|
||||
title: "Powershell Error: command not found: medusa",
|
||||
content: <PowershellErrorSection />
|
||||
},
|
||||
{
|
||||
title: "Yarn Error: command not found: medusa",
|
||||
content: <YarnErrorSection />
|
||||
}
|
||||
]}
|
||||
/>
|
||||
@@ -0,0 +1,31 @@
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
If you install the Medusa CLI tool with Yarn, then try to use the CLI tool but get the error:
|
||||
|
||||
```bash noReport
|
||||
command not found: medusa
|
||||
```
|
||||
|
||||
You have to add Yarn’s install location to the PATH variable:
|
||||
|
||||
<Tabs groupId="operating-systems" isCodeTabs={true}>
|
||||
<TabItem value="unix" label="MacOS / Linux" default>
|
||||
|
||||
```bash
|
||||
export PATH="$(yarn global bin):$PATH"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="windows" label="Windows">
|
||||
|
||||
```bash
|
||||
# MAKE SURE TO INCLUDE %path%
|
||||
setx path "%path%;c:\users\YOURUSERNAME\appdata\local\yarn\bin"
|
||||
# YOURUSERNAME is your account username
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
You can learn more in [Yarn’s documentation](https://classic.yarnpkg.com/en/docs/cli/global#adding-the-install-location-to-your-path).
|
||||
@@ -1,27 +1,9 @@
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
---
|
||||
title: 'General Errors'
|
||||
---
|
||||
|
||||
# Resolve "Cannot find module X" Errors
|
||||
import ModuleXErrorSection from './common-installation-errors/_module-x-error.mdx'
|
||||
|
||||
This error can occur while installing one of the storefronts or the Medusa admin. There is no specific cause to this error.
|
||||
## Resolve "Cannot find module X" Errors
|
||||
|
||||
One way to resolve it is by removing the `node_modules` directory in the project and re-installing the dependencies:
|
||||
|
||||
<Tabs groupId="operating-systems" isCodeTabs={true}>
|
||||
<TabItem value="unix" label="MacOS / Linux" default>
|
||||
|
||||
```bash
|
||||
rm -rf node_modules
|
||||
yarn install
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="windows" label="Windows">
|
||||
|
||||
```bash
|
||||
rd /s /q node_modules
|
||||
yarn install
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
<ModuleXErrorSection />
|
||||
@@ -0,0 +1,25 @@
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
This error can occur while installing any of Medusa's projects (for example, Next.js storefront). There is no specific cause to this error.
|
||||
|
||||
One way to resolve it is by removing the `node_modules` directory in the project and re-installing the dependencies:
|
||||
|
||||
<Tabs groupId="operating-systems" isCodeTabs={true}>
|
||||
<TabItem value="unix" label="MacOS / Linux" default>
|
||||
|
||||
```bash
|
||||
rm -rf node_modules
|
||||
yarn install
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="windows" label="Windows">
|
||||
|
||||
```bash
|
||||
rd /s /q node_modules
|
||||
yarn install
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
@@ -1,6 +1,8 @@
|
||||
# CORS issues
|
||||
---
|
||||
title: 'CORS issues'
|
||||
---
|
||||
|
||||
If you are experiencing connection issues when trying to access your Medusa backend from a storefront, it is most likely due to Cross-Origin Resource Sharing (CORS) issues.
|
||||
If you are experiencing connection issues when trying to access your Medusa backend from a storefront or the admin dashboard, it is most likely due to Cross-Origin Resource Sharing (CORS) issues.
|
||||
|
||||
You might see a log in your browser console, that looks like this:
|
||||
|
||||
|
||||
@@ -1,16 +0,0 @@
|
||||
# Common Create-React-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 backend.
|
||||
|
||||
To resolve this issue, make sure you change into the `backend` directory of the Medusa project you created before trying to start the Medusa backend:
|
||||
|
||||
```bash npm2yarn
|
||||
cd backend
|
||||
npx @medusajs/medusa-cli develop
|
||||
```
|
||||
|
||||
## Other Errors
|
||||
|
||||
If you ran into another error, please try to search through [our GitHub issues](https://github.com/medusajs/medusa/issues) to see if there's a solution for your issue. If not, please [create an issue on GitHub](https://github.com/medusajs/medusa/issues/new?assignees=olivermrbl&labels=status:+needs+triaging,+type:+bug&template=bug_report.md&title=) and our team will help you resolve it soon.
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: 'Common Create-React-App Errors'
|
||||
---
|
||||
|
||||
import TypeError from './create-medusa-app-errors/_typeerror.md'
|
||||
import OtherErrors from './create-medusa-app-errors/_other-errors.md'
|
||||
|
||||
## TypeError: cmd is not a function
|
||||
|
||||
<TypeError />
|
||||
|
||||
---
|
||||
|
||||
## Other Errors
|
||||
|
||||
<OtherErrors />
|
||||
@@ -0,0 +1 @@
|
||||
If you ran into another error, please try to search through [our GitHub issues](https://github.com/medusajs/medusa/issues) to see if there's a solution for your issue. If not, please [create an issue on GitHub](https://github.com/medusajs/medusa/issues/new?assignees=olivermrbl&labels=status:+needs+triaging,+type:+bug&template=bug_report.md&title=) and our team will help you resolve it soon.
|
||||
@@ -0,0 +1,8 @@
|
||||
This error typically occurs when you set up a Medusa project with `create-medusa-app` and try to run the Medusa backend.
|
||||
|
||||
To resolve this issue, make sure you change into the `backend` directory of the Medusa project you created before trying to start the Medusa backend:
|
||||
|
||||
```bash npm2yarn
|
||||
cd backend
|
||||
npx @medusajs/medusa-cli develop
|
||||
```
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: 'Database Errors'
|
||||
---
|
||||
|
||||
import SaslSection from './database-errors/_sasl.md'
|
||||
import ConnectionErrorSection from './database-errors/_connection-error.md'
|
||||
|
||||
## Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: Client password must be a string
|
||||
|
||||
<SaslSection />
|
||||
|
||||
---
|
||||
|
||||
## Error: connect ECONNREFUSED ::1:5432
|
||||
|
||||
<ConnectionErrorSection />
|
||||
@@ -0,0 +1,10 @@
|
||||
When you start your Medusa backend you may run into the following error:
|
||||
|
||||
```bash
|
||||
Error: connect ECONNREFUSED ::1:5432
|
||||
```
|
||||
|
||||
This error occurs because the backend 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 backend 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 `postgresql://[user[:password]@][host][:port][/dbname][?paramspec]`. Make sure that the connection URL format is correct, and the credentials passed in the URL are correct.
|
||||
+1
-3
@@ -1,6 +1,4 @@
|
||||
# Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: Client password must be a string
|
||||
|
||||
You can get the following error while running `medusa new` or while running integration tests during [local development](../development/fundamentals/local-development.md):
|
||||
You may get the following error while running `medusa new` or while running integration tests during [local development](../../development/fundamentals/local-development.md):
|
||||
|
||||
```bash
|
||||
Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a string
|
||||
@@ -1,4 +1,6 @@
|
||||
# Troubleshooting Documentation Errors
|
||||
---
|
||||
title: 'Troubleshooting Documentation Errors'
|
||||
---
|
||||
|
||||
## React Hook Errors
|
||||
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
# Errors After Update
|
||||
---
|
||||
title: 'Errors After Update'
|
||||
---
|
||||
|
||||
If you run into errors after updating Medusa and its dependencies, it's highly recommended to check the [Upgrade Guides](../upgrade-guides/index.mdx) if there is a specific guide for your version. These guides include steps required to perform after upgrading Medusa.
|
||||
|
||||
|
||||
@@ -1,11 +1,12 @@
|
||||
# Payment Processor (Stripe) not showing in checkout
|
||||
---
|
||||
title: 'Payment Processor not showing in checkout'
|
||||
---
|
||||
|
||||
You add payment processors to your Medusa instance by adding them as plugins in `medusa-config.js`:
|
||||
|
||||
```js title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
// You can create a Stripe account via: https://stripe.com
|
||||
{
|
||||
resolve: `medusa-payment-stripe`,
|
||||
options: {
|
||||
@@ -30,5 +31,5 @@ Then, refer to [this user guide](../user-guide/regions/providers.mdx) to learn h
|
||||
|
||||
## See Also
|
||||
|
||||
- [Install Stripe](../plugins/payment/stripe.md)
|
||||
- [Install Stripe](../plugins/payment/stripe.mdx)
|
||||
- [Payment Architecture Overview](../modules/carts-and-checkout/payment.md)
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
# Redis not emitting events
|
||||
---
|
||||
title: 'Redis not emitting events'
|
||||
---
|
||||
|
||||
:::note
|
||||
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
# S3 Plugin ACL Error
|
||||
---
|
||||
title: 'S3 Plugin ACL Error'
|
||||
---
|
||||
|
||||
If you're using the [S3 Plugin](../plugins/file-service/s3.md) and, when you upload an image, you receive the following error on your Medusa backend:
|
||||
If you're using the [S3 Plugin](../plugins/file-service/s3.mdx) and, when you upload an image, you receive the following error on your Medusa backend:
|
||||
|
||||
```bash noReport
|
||||
AccessControlListNotSupported: The bucket does not allow ACLs
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
# Signing in to Medusa Admin
|
||||
---
|
||||
title: 'Signing in to Medusa Admin'
|
||||
---
|
||||
|
||||
If you've created a new Medusa backend and used the `seed` command, the default credentials are:
|
||||
|
||||
@@ -17,4 +19,4 @@ npx @medusajs/medusa-cli user -e some@email.com -p somepassword
|
||||
|
||||
## See Also
|
||||
|
||||
- [Medusa CLI tool reference](../cli/reference.md)
|
||||
- [Medusa CLI tool reference](../cli/reference.mdx)
|
||||
|
||||
Reference in New Issue
Block a user