docs: added troubleshooting guides + improvements (#11927)
* docs: added troubleshooting guides + improvements * build fixes
This commit is contained in:
Shahed Nasser
GitHub
@@ -0,0 +1,51 @@
|
||||
If you see the following error in the Medusa Admin's console:
|
||||
|
||||
```bash
|
||||
Blocked request. This host (X) is not allowed. To allow this host, add X to server.allowedHosts in vite.config.js.
|
||||
```
|
||||
|
||||
Where `X` is the host that's being blocked. For example, `example.com`.
|
||||
|
||||
## Why this Error Occurred
|
||||
|
||||
This error occurs if you deploy Medusa but are using development mode (`NODE_ENV=development`). This can happen accidentally or unintentionally, but Medusa defaults `NODE_ENV` to `production`.
|
||||
|
||||
## How to Fix it
|
||||
|
||||
### Option 1: Use Production Mode
|
||||
|
||||
To resolve this error, ensure that you're running Medusa in production mode. You can set the `NODE_ENV` environment variable to `production` when starting Medusa:
|
||||
|
||||
```bash
|
||||
NODE_ENV=production
|
||||
```
|
||||
|
||||
### Option 2: Allow the Host
|
||||
|
||||
If you intentionally want to use development mode in your deployed Medusa instance, you can allow the host that's being blocked using the `admin.vite` configuration in `medusa-config.ts`.
|
||||
|
||||
For example:
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
// ...
|
||||
admin: {
|
||||
vite: () => {
|
||||
return {
|
||||
server: {
|
||||
allowedHosts: [".example.com"],
|
||||
},
|
||||
}
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
In the above example, you allow the host `example.com` to access the Medusa Admin. Make sure that when you replace `example.com` with your actual host, you include the leading `.` before the domain name.
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Environment Variables](!docs!/learn/fundamentals/environment-variables)
|
||||
- [admin.vite Configuration](!docs!/learn/configurations/medusa-config#vite)
|
||||
@@ -0,0 +1,22 @@
|
||||
If you send a request to an API route and receive the following error:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "invalid_data",
|
||||
"message": "Invalid request: Unrecognized fields: 'additional_data'"
|
||||
}
|
||||
```
|
||||
|
||||
## Why this Error Occured
|
||||
|
||||
This error occurs when you send the `additional_data` request body parameter to a route that doesn't support it.
|
||||
|
||||
The [Additional Data property](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data) is useful to pass custom data to an API route, but it's not supported by all API routes.
|
||||
|
||||
---
|
||||
|
||||
## How to Fix it
|
||||
|
||||
For the list of API routes that support passing `additional_data`, refer to the [Additional Data documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/additional-data).
|
||||
|
||||
If the route you need isn't on the list, you have to create a custom API route with your desired functionality.
|
||||
@@ -0,0 +1,23 @@
|
||||
If you get the following error after creating a new data model in your Medusa application:
|
||||
|
||||
```bash
|
||||
error: Error: Cannot define field(s) "created_at,updated_at,deleted_at" as they are implicitly defined on every model
|
||||
```
|
||||
|
||||
The error may include the three fields, or only some of them, based on which fields you're trying to define in the data model.
|
||||
|
||||
## Why this Error Occurred
|
||||
|
||||
This error occurs because you're trying to define the `created_at`, `updated_at`, or `deleted_at` properties on a new data model. These properties are implicitly defined on every data model in Medusa and can't be redefined.
|
||||
|
||||
---
|
||||
|
||||
## How to Fix it
|
||||
|
||||
To resolve this error, remove the `created_at`, `updated_at`, and `deleted_at` properties from your data model definition. You'll still be able to use these properties in your application, but you can't redefine them in your data models.
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Data Model's Default Properties](!docs!/learn/fundamentals/data-models/properties#data-models-default-properties)
|
||||
@@ -0,0 +1,55 @@
|
||||
If you get the following error in your Medusa application's terminal:
|
||||
|
||||
```bash
|
||||
Trying to query by not existing property LinkModel.X.
|
||||
```
|
||||
|
||||
Where `X` is the name of a data model. For example, `LinkModel.cart`.
|
||||
|
||||
## Why this Error Occurred
|
||||
|
||||
This error occurs when you're using Query and you're trying to filter by a linked module, which isn't allowed.
|
||||
|
||||
For example, assuming you have a `Post` data model and you linked it to the `Cart` data model, this isn't allowed:
|
||||
|
||||
```ts
|
||||
const { data } = await query.graph({
|
||||
entity: "post",
|
||||
fields: ["*"],
|
||||
filter: {
|
||||
cart: {
|
||||
id: "cart_123",
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
You can't filter your custom `post` data model by the ID of their linked cart.
|
||||
|
||||
---
|
||||
|
||||
## How to Fix it
|
||||
|
||||
You need to query the link's table directly and apply the filters on its ID columns. For example:
|
||||
|
||||
```ts
|
||||
import PostCartLink from "../links/post-cart"
|
||||
|
||||
// ...
|
||||
|
||||
const { data } = await query.graph({
|
||||
entity: PostCartLink.entryPoint,
|
||||
fields: ["post.*", "cart.*"],
|
||||
filters: {
|
||||
cart_id: "cart_123",
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
In the above example, you query the `PostCartLink` data model directly and apply the filters to the `cart_id` field, which holds the ID of the cart linked to the post. You'll then only retrieve the posts linked to the cart with the ID `cart_123`.
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Query](!docs!/learn/fundamentals/module-links/query#apply-filters-and-pagination-on-linked-records)
|
||||
@@ -0,0 +1,86 @@
|
||||
If you get the following error when using Query to retrieve records of your custom data model:
|
||||
|
||||
```bash
|
||||
service.list is not a function
|
||||
```
|
||||
|
||||
## Why this Error Occurred
|
||||
|
||||
To retrieve records of your data model, Query uses the `listX` method of your module's service.
|
||||
|
||||
For example, if you have a Blog Module and you are trying to retrieve posts, Query will try to call the `listPost` method of the Blog Module's service. If it doesn't find the method, it will throw the above error.
|
||||
|
||||
---
|
||||
|
||||
## How to Fix it
|
||||
|
||||
### Option 1: Extend Service Factory
|
||||
|
||||
To resolve this error, make sure that your module's service has a `listX` method that returns the records of your data model.
|
||||
|
||||
This method is generated for you if your service extends `MedusaService`:
|
||||
|
||||
```ts title="src/modules/blog/service.ts"
|
||||
import { MedusaService } from "@medusajs/framework/utils"
|
||||
import Post from "./models/post"
|
||||
|
||||
class BlogModuleService extends MedusaService({
|
||||
Post,
|
||||
}){
|
||||
}
|
||||
|
||||
export default BlogModuleService
|
||||
```
|
||||
|
||||
In the above example, the `listPost` method is generated for you because the `BlogModuleService` extends `MedusaService`.
|
||||
|
||||
### Option 2: Implement the Method
|
||||
|
||||
If your module is returning data from a third-party service, or you have some custom mechanism to define and manage your data models, then you need to implement the `list` or just `list` method in your service.
|
||||
|
||||
For example:
|
||||
|
||||
```ts title="src/modules/blog/service.ts"
|
||||
type BlogModuleOptions = {
|
||||
apiKey: string
|
||||
}
|
||||
|
||||
export default class BlogModuleService {
|
||||
private client
|
||||
|
||||
constructor({}, options: BlogModuleOptions) {
|
||||
this.client = new Client(options)
|
||||
}
|
||||
|
||||
async list(
|
||||
filter: {
|
||||
id: string | string[]
|
||||
}
|
||||
) {
|
||||
return this.client.getPosts(filter)
|
||||
/**
|
||||
* Example of returned data:
|
||||
*
|
||||
* [
|
||||
* {
|
||||
* "id": "post_123",
|
||||
* "product_id": "prod_321"
|
||||
* },
|
||||
* {
|
||||
* "id": "post_456",
|
||||
* "product_id": "prod_654"
|
||||
* }
|
||||
* ]
|
||||
*/
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Query](!docs!/learn/fundamentals/module-links/query)
|
||||
- [Service Factory documentation](!docs!/learn/fundamentals/modules/service-factory)
|
||||
- [Service Factory reference](../../../service-factory-reference/page.mdx)
|
||||
- [Example: Read-Only Module Link for Virtual Data Models](!docs!/learn/fundamentals/module-links/read-only#example-read-only-module-link-for-virtual-data-models)
|
||||
@@ -0,0 +1,18 @@
|
||||
If you send a request to the `/store/products` or `/store/products/:id` API routes and receive the following error in the response:
|
||||
|
||||
```bash
|
||||
{
|
||||
"type": "invalid_data",
|
||||
"message": "Publishable key needs to have a sales channel configured."
|
||||
}
|
||||
```
|
||||
|
||||
## Why this Error Occurred
|
||||
|
||||
This error means you passed a valid `x-publishable-api-key` header, but the key does not have a sales channel configured. The sales channel is required to make requests to the `/store/products` and `/store/products/:id` routes, as it's used to retrieve products available in that sales channel.
|
||||
|
||||
---
|
||||
|
||||
## How to Fix it
|
||||
|
||||
To resolve this error, you need to add at least one sales channel to your publishable API key. Refer to the [Manage Publishable API Key User Guide](!user-guide!/settings/developer/publishable-api-keys#manage-publishable-api-keys-sales-channels) to learn how to do that.
|
||||
@@ -0,0 +1,33 @@
|
||||
If you receive the following error response when you send a request to a `/store` route:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "not_allowed",
|
||||
"message": "Publishable API key required in the request header: x-publishable-api-key. You can manage your keys in settings in the dashboard."
|
||||
}
|
||||
```
|
||||
|
||||
## Why this Error Occurred
|
||||
|
||||
This error occurs because the request is missing the `x-publishable-api-key` header. The `x-publishable-api-key` header is required for all requests to the `/store` route.
|
||||
|
||||
---
|
||||
|
||||
## How to Fix it
|
||||
|
||||
To resolve this error, add the `x-publishable-api-key` header to your request. You can find your publishable API key in the [Medusa Admin Dashboard](!user-guide!/settings/developer/publishable-api-keys).
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
curl -X GET https://localhost:9000/store/products \
|
||||
-H "x-publishable-api-key: your-publishable-api-key"
|
||||
```
|
||||
|
||||
Where `your-publishable-api-key` is your publishable API key.
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [API reference](!api!/store#publishable-api-key)
|
||||
@@ -0,0 +1,32 @@
|
||||
The Next.js Starter Storefront uses parallel routes to show account pages. However, there's a [reported error](https://github.com/vercel/next.js/issues/71626) when hosting Next.js with parallel routes on Google's Cloud Run, where the error stops working.
|
||||
|
||||
## Why this Error Occurred
|
||||
|
||||
This error occurs because Google Cloud Run decodes chunk URLs, but Next.js expects them to be encoded.
|
||||
|
||||
---
|
||||
|
||||
## How to Fix it
|
||||
|
||||
To resolve the error, add the following rewrites in your Next.js Starter Storefront's `next.config.ts` file:
|
||||
|
||||
```ts title="next.config.ts"
|
||||
const nextConfig = {
|
||||
// ... other config
|
||||
rewrites: async () => {
|
||||
return {
|
||||
beforeFiles: [
|
||||
{
|
||||
source: "/_next/static/chunks/app/:folder*/@login/:path*",
|
||||
destination: "/_next/static/chunks/app/:folder*/%40login/:path*",
|
||||
},
|
||||
// Repeat this pattern if other similar errors occur
|
||||
],
|
||||
afterFiles: [],
|
||||
fallback: [],
|
||||
}
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
You can add the rewrite to other parallel routes you have in your application. For example, if you have a `/@dashboard` route, you can add a rewrite for it as well.
|
||||
@@ -0,0 +1,45 @@
|
||||
If you get the following error when you start the Medusa application:
|
||||
|
||||
```bash
|
||||
Error: Step X is already defined in workflow.
|
||||
```
|
||||
|
||||
Where `X` is any step, such as `create-remote-link`.
|
||||
|
||||
## Why this Error Occurred
|
||||
|
||||
This error indicates that you're re-using a step in a workflow, meaning that more than one step in the workflow have the same name.
|
||||
|
||||
---
|
||||
|
||||
## How to Fix it
|
||||
|
||||
To resolve this error, use the `config` method of a step to specify a custom name within the workflow's scope. For example:
|
||||
|
||||
```ts
|
||||
const helloWorkflow = createWorkflow(
|
||||
"hello",
|
||||
() => {
|
||||
const { data: products } = useQueryGraphStep({
|
||||
entity: "product",
|
||||
fields: ["id"],
|
||||
})
|
||||
|
||||
// ✓ No error occurs, the step has a different ID.
|
||||
const { data: customers } = useQueryGraphStep({
|
||||
entity: "customer",
|
||||
fields: ["id"],
|
||||
}).config({ name: "fetch-customers" })
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
In the above example, you use the `config` method on the second `useQueryGraphStep` usage to change its name to `fetch-customers`.
|
||||
|
||||
Make sure to change the name of every usage after the first one in a workflow.
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Multiple Step Usage in Workflow documentation](https://docs.medusajs.com/learn/fundamentals/workflows/multiple-step-usage)
|
||||
@@ -0,0 +1,9 @@
|
||||
import AdditionalDataError from "../_sections/api-routes/additional-data.mdx"
|
||||
|
||||
export const metadata = {
|
||||
title: `Unrecognized fields \`additiona_data\` Error`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<AdditionalDataError />
|
||||
@@ -0,0 +1,9 @@
|
||||
import DataModelDefaults from "../../_sections/data-models/default-fields.mdx"
|
||||
|
||||
export const metadata = {
|
||||
title: `Can't define fields Error`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<DataModelDefaults />
|
||||
@@ -0,0 +1,9 @@
|
||||
import AdminBlockedRequest from "../../_sections/admin/blocked-request.mdx"
|
||||
|
||||
export const metadata = {
|
||||
title: `Blocked Request Error in Medusa Admin`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<AdminBlockedRequest />
|
||||
@@ -0,0 +1,9 @@
|
||||
import RewritesTroubleshooting from "../_sections/storefront/rewrites.mdx"
|
||||
|
||||
export const metadata = {
|
||||
title: `Next.js Starter Storefront Login Page Error on Google Cloud Run`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<RewritesTroubleshooting />
|
||||
@@ -0,0 +1,9 @@
|
||||
import NotExistingPropertyError from "../../_sections/query/not-existing-property.mdx"
|
||||
|
||||
export const metadata = {
|
||||
title: `Trying to query by not existing property Error`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<NotExistingPropertyError />
|
||||
@@ -0,0 +1,9 @@
|
||||
import ServiceListError from "../../_sections/query/service-list.mdx"
|
||||
|
||||
export const metadata = {
|
||||
title: `service.list is not a function Error`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<ServiceListError />
|
||||
@@ -0,0 +1,9 @@
|
||||
import PakTroubleshooting from "../_sections/storefront/pak.mdx"
|
||||
|
||||
export const metadata = {
|
||||
title: `Publishable API key required Error`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<PakTroubleshooting />
|
||||
@@ -0,0 +1,9 @@
|
||||
import PakScTroubleshooting from "../_sections/storefront/pak-sc.mdx"
|
||||
|
||||
export const metadata = {
|
||||
title: `Publishable API needs to have a sales channel Error`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<PakScTroubleshooting />
|
||||
@@ -1,24 +0,0 @@
|
||||
export const metadata = {
|
||||
title: `Workflow Errors`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
## When-Then Error: Handler for action X Not Found
|
||||
|
||||
The following error may occur in production if you use a `when-then` block in your workflow:
|
||||
|
||||
```plain
|
||||
custom-workflow:when-then-01JE8Z0M1FXSE2NCK1G04S0RR2:invoke - Handler for action \"when-then-01JE8Z0M1FXSE2NCK1G04S0RR2\" not found...
|
||||
```
|
||||
|
||||
This occurs if the `when-then` block doesn't return a step's result and doesn't have a name specified. You can resolve it by passing a name as a first parameter of `when`:
|
||||
|
||||
```ts
|
||||
const result = when(
|
||||
"custom-when-condition"
|
||||
// ... rest of the parameters
|
||||
)
|
||||
```
|
||||
|
||||
Learn more about passing a name for `when-then` in [this documentation](!docs!/learn/fundamentals/workflows/conditions#specify-name-for-when-then)
|
||||
@@ -0,0 +1,9 @@
|
||||
import StepXDefined from "../../_sections/workflows/step-x-defined.mdx"
|
||||
|
||||
export const metadata = {
|
||||
title: `Step X is already defined in workflow Error`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<StepXDefined />
|
||||
@@ -0,0 +1,49 @@
|
||||
export const metadata = {
|
||||
title: `Handler for action X Not Found Workflow Error`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
The following error may occur in production if you use a `when-then` block in your workflow:
|
||||
|
||||
```plain
|
||||
custom-workflow:when-then-01JE8Z0M1FXSE2NCK1G04S0RR2:invoke - Handler for action \"when-then-01JE8Z0M1FXSE2NCK1G04S0RR2\" not found...
|
||||
```
|
||||
|
||||
## Why this Error Occured
|
||||
|
||||
This error occurs if the `when-then` block doesn't return a step's result and doesn't have a name specified.
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
when(input, (input) => !input.is_active)
|
||||
.then(() => {
|
||||
console.log("not returning anything")
|
||||
})
|
||||
```
|
||||
|
||||
The above `when-then` block doesn't return a step's result, which causes the error.
|
||||
|
||||
---
|
||||
|
||||
## How to Fix it
|
||||
|
||||
You can resolve this error by passing a name as a first parameter of `when`:
|
||||
|
||||
```ts
|
||||
const result = when(
|
||||
"custom-when-condition",
|
||||
input,
|
||||
(input) => !input.is_active
|
||||
)
|
||||
.then(() => {
|
||||
console.log("not returning anything")
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [When-Then documentation](!docs!/learn/fundamentals/workflows/conditions#specify-name-for-when-then)
|
||||
Reference in New Issue
Block a user