Troubleshooting

This page collects the issues we see most often. For deeper diagnostics, every call to the marketplace is recorded in the API Logs list (Dashboard → Quick Start → API Logs) with the full request, response, headers, status and timing.

Confirm the plugin is activated under Extensions → My extensions.
Clear the admin cache via the standard Shopware admin cache clear procedure.
Hard-reload the admin (Ctrl+Shift+R) so the browser fetches the new bundle.
If you build the administration yourself, re-run the appropriate build command.
Check that your user role has access to the plugin’s permissions in the role configuration.

The entry appears under Catalogues with a blue shopping-bag icon. All plugin pages are reached from the Mirakl Dashboard, either via the setup steps or the Quick Start tiles.

”Invalid API key” / authentication errors on Test Connection

Re-copy the key from the marketplace seller dashboard. Whitespace at the start or end is the most common cause.
Some marketplaces expire keys after a period of inactivity — generate a fresh one.
Check the Instance URL — it should look like https://marketplace.example.com, without /api appended and without a trailing slash.
Check the Shop ID — required on most marketplaces. Copying the wrong shop id from a multi-shop seller account is a common cause.
If you proxy the marketplace API through an internal gateway, confirm that the Authorization header is forwarded unchanged.
A failed test flips the connection to status Error and shows the marketplace’s message — hover over the status, or open the Edit Connection modal to see it.

Product export errors

Common messages and what to do about them:

“Category not mapped” — open Mirakl → Quick Start → Categories, click the marketplace category, switch to the Mapping tab and add the Shopware category. See Categories.
“Required attribute missing” — open Mirakl → Quick Start → Attribute Mappings, find the required attribute and map it to a Shopware product field, custom field or property group.
“Invalid attribute value” — set up a value transformation on the attribute mapping to convert your Shopware value into one the marketplace accepts (replacement, regex, lowercase, max-length). See Value transformations.
“Offer state unknown” — refresh the offer states from the Offer States page (Refresh Mirakl States), then either set a Default Offer State in Edit Connection, or override it per product (see below).

For per-line errors on a finished export, sort the Product Catalog list by Export Status = error to see which products failed and why.

Stuck syncs / no progress

Confirm the worker (messenger:consume async) is actually running.
Confirm the scheduler (scheduled-task:run) is in your cron or runs periodically.
The throttle lock frees itself within a minute — if a job is still stuck after that, check the Tasks list (Dashboard → Quick Start → Tasks) for the entry’s status and the latest message.
If a row in Sync Logs has been in Started status for hours with no completion time, the worker died part-way through the run. Open the Related Logs tab on the row and look at the linked API Logs entries to see how far the marketplace call got.
For rate-limited handlers, the message is re-queued with a delay — it will resume automatically when the delay expires. See API throttling.

Order import returns nothing despite new orders existing

Check the Initial Order Import Date on the connection (wizard step 12) — only orders updated after this date are imported on the first run. If you set it to a future date, the first run returns nothing.
After the first run, the plugin remembers the last imported order’s timestamp and resumes from there. If the marketplace’s clocks drift, you might briefly miss orders — the next scheduled run catches up.
The Sync Logs row for the run shows Processed = 0 if the marketplace returned an empty page. Open the linked API Logs entry to see the actual response.
Confirm Enable Order Import is on under Mirakl → Settings → Sync Settings.

Rate-limit messages in the Sync Logs

The plugin reacts to rate limits by re-queuing the message with the marketplace’s requested delay. Eventual completion is guaranteed, but throughput drops.
The plugin’s own one-minute pacing only covers product imports, offer imports and stock imports. Other syncs (order import, message sync, document sync, invoice sync, transaction-log sync) rely on the marketplace’s rate-limit response alone.
For chronic rate-limit messages on the non-paced syncs, raise the corresponding interval on Mirakl → Settings → Sync Settings.
Don’t share an API key across two Shopware instances — each instance paces its own calls, but the marketplace counts the combined load. Use one instance per seller account.

See API throttling for the full picture.

Offer not updating on the marketplace after a Shopware edit

Open the Offer Mappings page and check the offer’s sync status. It should be in Queued or Retry for the change to be picked up.
If it’s Synced, the plugin thinks nothing changed since the last sync — unchanged uploads are skipped. Force a re-sync from the Dashboard → connection card → Sync All Offers.
If it’s Error, the latest error is shown on the row — usually a category change made the offer invalid for its current marketplace category, or a required offer field is now missing.
Stock-only changes are handled by the Stock sync task on a 15-minute interval and by the immediate change push — they don’t affect the full-offer sync status.

Message / document / invoice / transaction-log sync inactive

These five (Enable Message Sync, Enable Order Document Sync, Enable Document Requests Sync, Enable Invoice Sync, Enable Transaction Log Sync) are off by default. Switch them on per use case on Mirakl → Settings → Sync Settings.
After enabling, the initial backfill runs once. Watch the Sync Logs for its progress — if it gets interrupted, the cursor remembers where it was and the next scheduled run resumes from there.

Database growing too fast

API log — every marketplace call is one row with full request and response. API log cleanup removes rows older than API Log Retention (days) (default 30).
Sync log — every long-running run and every one-shot event writes a row (unless its level is unticked). Sync log cleanup removes rows older than Sync Log Retention (days) (default 30).
Task progress — Task progress cleanup removes finished entries once a day.
Export records — Export cleanup removes finished product-export rows and their generated CSV files once an hour.
Transaction log — financial data, no automatic retention. Archive it to a separate store if you exceed your DB size budget.

If you see runaway growth, confirm the scheduler is running — without it, none of the cleanup tasks ever fire.

Where to look first

Sync Logs (Dashboard → Quick Start → Logs) — high-level “what was attempted, processed, failed”.
API Logs (Quick Start → API Logs) — the raw HTTP call with the full request and response, filterable by date, connection and type.
Tasks (Quick Start → Tasks) — for admin-triggered tasks: percentage, latest message.
Imports (Quick Start → Imports) and Product Exports (Quick Start → Product Exports) — marketplace-side import jobs with their statuses and per-line errors.

If you still can’t find the cause, the API Logs entry for the failing call is the artefact to share with support.