Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/aerele/medusa_integration/llms.txt

Use this file to discover all available pages before exploring further.

This page covers the most common problems encountered when running the ERPNext Medusa Integration and provides concrete steps for diagnosing and resolving each one. For every issue, the Medusa Request Log and the ERPNext Error Log are your primary diagnostic tools — check them first before making any configuration changes.

​
How to check the Medusa Request Log

Every HTTP call the integration makes to Medusa is recorded automatically in Desk → Medusa Request Log. Each entry shows:
  • Status — Success (HTTP 2xx) or Failure (any other response)
  • Payload — the JSON body sent to Medusa, pretty-printed
  • Response — the JSON body (or raw text) returned by Medusa
  • Voucher Type / Voucher Name — the ERPNext document that triggered the call
Filter by status = Failure to see only failed requests. The response field will contain the error message returned by Medusa, which is usually the most informative signal.
If you are investigating a specific document (e.g., a particular Sales Order), filter the log by Voucher Name to see every API call made for that record.

​
Common issues

The most common cause is that the integration is disabled at the configuration level.
1

Open Medusa Configuration

In ERPNext Desk, search for Medusa Configuration and open the single record.
2

Check the Enable checkbox

Confirm that the Enable checkbox is ticked. If it is unchecked, all outbound API calls are suppressed globally — no document events, no scheduled tasks, and no manual actions will reach Medusa.
3

Verify the API URL

Check that the Medusa URL field contains the correct base URL for your Medusa instance, including the protocol (e.g., https://api.example.com). There should be no trailing slash.
4

Save and test

Save the configuration record, then trigger a test action (for example, save a Website Item) and check the Medusa Request Log for a new entry.
The integration authenticates with Medusa using an admin email and password stored in Medusa Configuration. When a request returns "Unauthorized", the integration automatically attempts to refresh the access token by re-authenticating, then retries the request.If the retry also fails, an Unauthorized response will appear in the Medusa Request Log.
1

Check admin credentials

Open Medusa Configuration and verify that the Admin Email and Admin Password fields match an active admin account in your Medusa backend.
2

Confirm the admin account exists in Medusa

Log in to your Medusa admin panel and confirm the account has not been deleted, disabled, or had its password changed.
3

Update credentials and save

If the credentials are wrong, update them in Medusa Configuration and save. The next API call will use the new credentials.
1

Check that the Website Item is published

Open the Website Item and confirm the Published checkbox is ticked. The integration only exports published items.
2

Check the item group has a Medusa ID

The item’s Item Group must have a medusa_id set (it maps to a Medusa collection). If the item group has no medusa_id, the integration will attempt to create the collection first. If that creation fails, the product export will also fail. Check the Medusa Request Log for a failed request with voucher_type = "Item Group".
3

Export item groups manually if needed

If item groups are missing their medusa_id, call the export_all_item_groups() function manually from the ERPNext console or a custom script to seed all collections in Medusa before exporting products.
4

Check the Medusa Request Log for errors

Filter by the Website Item name in the Voucher Name column. A Failure entry will show the exact error response from Medusa (e.g., duplicate handle, missing field, or validation error).
The Medusa storefront calls ERPNext API endpoints to create quotations and sales orders. If orders are not appearing:
1

Verify the storefront is calling the correct ERPNext URL

Check your Medusa storefront configuration (environment variables or settings) to confirm it is pointing to the correct ERPNext site URL. A mismatch here means all API calls go to the wrong server or fail silently.
2

Check the ERPNext Error Log

In ERPNext Desk, open Error Log and look for recent errors from the create_quotation or update_quotation functions. Common causes are missing customer medusa_id, an item code not found for a variant ID, or a validation error during document insertion.
3

Check that the customer exists in ERPNext

The order creation flow looks up the customer by medusa_id. If no Customer or Lead with the given medusa_id exists in ERPNext, the API will return an error to the storefront.
1

Check the price list

Only Item Price records with price_list = "Standard Selling" are synced automatically. If your price is on a different price list, it will not be pushed.
2

Check that no customer is set

Customer-specific Item Prices (negotiated prices) are intentionally excluded from automatic Medusa sync. Only generic standard prices are pushed.
3

Check the medusa_price_id field

Open the Item Price record and look for the medusa_price_id field. If it is blank, the price has not been synced. Trigger a save on the record (or wait for the nightly sync_missing_prices_to_medusa task) to push it.
4

Check that the Website Item has a medusa_variant_id

The price sync requires a medusa_variant_id on the corresponding Website Item. If the item has not been exported to Medusa yet, the price cannot be synced. Export the item first, then re-save the Item Price.
5

Check the Medusa Request Log

Filter by voucher_type = "Item Price" and look for Failure entries to see any error responses from Medusa.
1

Verify the scheduler is enabled

Run the following command on your ERPNext server:
bench --site <your-site-name> scheduler status
If it reports disabled, enable it:
bench --site <your-site-name> enable-scheduler
2

Check the Scheduled Job Log

In ERPNext Desk, open Scheduled Job Log and filter by the task function name (e.g., medusa_integration.api.send_quotation_emails). If there are no entries at all, the scheduler worker may not be running.
3

Verify background workers are running

Check that the bench worker and bench schedule processes are active on your server. Use supervisorctl status or equivalent process management to confirm.
The export_items_and_images_custom task splits work into four parallel jobs on the long queue. If the export is not completing:
1

Confirm the long-queue worker is running

The four batch jobs are enqueued on queue="long". Verify that a worker for this queue is active:
bench worker --queue long
If this process is not running, all long-queue jobs will accumulate without executing.
2

Check Error Log for batch failures

Each batch job wraps individual item exports in a try/except block and calls frappe.log_error() on failure. Open Error Log and filter by title containing "Error exporting" to find items that failed individually.
3

Check for items stuck with no medusa_id

If the bulk export ran but some items were skipped, query Website Items where published = 1 and medusa_id is blank. These items can be re-exported by saving them individually or by waiting for the next nightly run of the scheduled task.
4

Check Medusa Request Log for API errors

Batch export failures often show up as Failure entries in the Medusa Request Log with errors such as duplicate product handle or invalid field value. Correct the data on the Website Item and retry.
Each batch job has an 8-hour timeout (timeout=28800). If your product catalogue is very large, consider running the initial export during off-peak hours.

​
General debugging tips

The ERPNext Error Log (Desk → Error Log) captures all unhandled exceptions from the integration, including those raised inside scheduled tasks, document event hooks, and API endpoints. When an issue is not visible in the Medusa Request Log, check the Error Log next.
You can also tail the Frappe log file directly on the server for real-time output during a debugging session: 
tail -f /home/frappe/frappe-bench/logs/worker.error.log
For issues that only occur during specific API calls from the storefront, enable ERPNext’s built-in request logging or add temporary frappe.log_error() calls in the relevant api.py functions to capture intermediate state.

Build docs developers (and LLMs) love

Get started for freeTalk to us