Troubleshooting

Troubleshooting

API Connection Issues

Test Connection Fails

1. Verify the API endpoint URL is correct (should look like https://your-instance.mirakl.net)
2. Confirm the API key has the required permissions in Mirakl
3. Check that your server can reach the Mirakl endpoint:

   curl -I https://your-instance.mirakl.net/api/account

4. View the API Health page (Mirakl → API Health) for detailed diagnostics

"cURL error 60: SSL certificate"

Your server is missing CA certificates. Solutions:

• Update the CA bundle on your server
• Or configure WordPress to use the system CA bundle:

  add_filter('http_request_args', function ($args) {
      $args['sslcertificates'] = ABSPATH . WPINC . '/certificates/ca-bundle.crt';
      return $args;
  });

Synchronization Issues

Orders Not Importing

1. Check Mirakl → Sync Schedule — order import must be enabled
2. Check Mirakl → Sync Logs for error messages
3. Verify the store credentials are still valid
4. Run a manual import from the Orders page (Mirakl → Orders → Import Orders)
5. Ensure the store is set to Active in Stores settings

Stock Not Syncing

1. Verify product has _mirakl_active = 'yes'
2. Check the product has a valid SKU
3. Confirm the SKU exists in the offer SKU cache (auto-populated from OF21)
4. Check sync logs for errors
5. Run manual stock sync from the Stock page

Pricing Import Fails

1. Check Mirakl → Prices → Pricing Imports for import status and error reports
2. Common issues:
   • Product SKU not found in Mirakl
   • Price format incorrect (use decimal format)
   • Currency mismatch
3. View the error report JSON for per-row failure details
4. Re-submit after fixing errors

Delivery Notes

PDF Not Generating

1. Check the order has _mirakl_order_id meta
2. Verify the user has manage_woocommerce capability
3. Check server has PHP dom extension installed
4. Ensure /tmp is writable (Dompdf uses it for font caching)
5. Check PHP error logs for Dompdf exceptions

Logo Not Appearing

1. Verify the logo was uploaded in Mirakl → Stores → Delivery Note section
2. GD library must be installed for image resizing
3. If GD is unavailable, the original image is used (may be too large)
4. Re-upload the logo to regenerate the base64 data

Attribute Mapping

Category Tree Empty

1. Click Sync Attributes to refetch from PM11 API
2. Check the Mirakl API connection is working
3. Verify the store has categories defined in Mirakl

Values Not Showing in Autocomplete

1. Locale filtering may be hiding non-matching values
2. Check the store's language setting (Mirakl → Stores)
3. Values without locale suffixes are always shown
4. The code field is what appears in the datalist, not the label

Cron Issues

Sync Jobs Not Running

1. Verify WordPress cron is functioning:

   curl -s https://yoursite.com/wp-cron.php?doing_wp_cron=1

2. Check Mirakl → Sync Schedule that intervals are set
3. Consider setting up a system cron as a fallback:

   * * * * * wget -q -O - https://yoursite.com/wp-cron.php?doing_wp_cron=1

4. Check for sync locks that may not have expired (Mirakl_Sync_Lock TTL: 360s)

"Lock already acquired" Messages

If a sync is stuck, the lock will auto-expire after 360 seconds. For immediate resolution:

1. Wait for lock TTL to expire
2. Or manually clear the sync lock from the database (mirakl_sync_locks table)

WooCommerce Order Issues

Duplicate Orders

1. Check mirakl_fetch_times — if the fetch cursor is incorrect, duplicate orders may be imported
2. The plugin checks mirakl_order_id uniqueness per store before creating orders
3. If duplicates exist, delete duplicates from {$prefix}mirakl_orders and the duplicate WC orders

Missing Mirakl Actions Panel

The Mirakl Actions panel on the order edit page only appears if the order has _mirakl_order_id or mirakl_order_id postmeta. If missing:

1. Check if the order was imported from Mirakl
2. Verify the meta key is correct
3. Check the render_order_actions_panel() hook is not being overridden by another plugin

Email Issues

Customers Receiving Duplicate Emails

The plugin suppresses WooCommerce customer emails for Mirakl-imported orders. If emails are still being sent:

1. Check that _mirakl_order_id meta exists on the order
2. Verify the maybe_disable_mirakl_order_email() hooks are registered
3. Check for other plugins that may re-enable email sending

Performance

Slow Admin Pages

The plugin caches API responses in custom tables. If pages are slow:

1. Check PHP memory limit (recommend 512 MB for large catalogs)
2. Large offer SKU caches may slow queries — ensure mirakl_offer_sku_cache has proper indexes
3. Attribute mapping with many categories may take time to load

Large Pricing Imports

For stores with thousands of products, pricing imports generate large requests:

1. Monitor PHP execution time limits
2. Consider increasing the polling delay
3. Check error reports for timeout-related failures