Fehlerbehebung

Diese Seite sammelt die Probleme, die wir am häufigsten sehen. Für tiefere Diagnose ist jeder Marktplatz-Aufruf in der Liste API Logs (Dashboard → Quick Start → API Logs) mit vollständiger Anfrage, Antwort, Header, Status und Laufzeit aufgezeichnet.

Das Menü „Mirakl” erscheint nach der Installation nicht

Stellen Sie sicher, dass das Plugin unter Erweiterungen → Meine Erweiterungen aktiviert ist.
Leeren Sie den Admin-Cache über die übliche Shopware-Prozedur.
Laden Sie den Adminbereich hart neu (Strg+Umschalt+R), damit der Browser das neue Bundle holt.
Wenn Sie die Administration selbst bauen, führen Sie den entsprechenden Build-Befehl erneut aus.
Prüfen Sie, dass Ihre Benutzerrolle in der Rollenkonfiguration Zugriff auf die Berechtigungen des Plugins hat.

Der Eintrag erscheint unter Kataloge mit einem blauen Einkaufstaschen-Symbol. Alle Plugin-Seiten erreichen Sie über das Mirakl-Dashboard, entweder über die Einrichtungsschritte oder die Kacheln unter Quick Start.

„Invalid API key” / Authentifizierungsfehler beim Verbindungstest

Kopieren Sie den Schlüssel erneut aus dem Verkäufer-Dashboard des Marktplatzes. Leerzeichen am Anfang oder Ende sind die häufigste Ursache.
Manche Marktplätze lassen Schlüssel nach längerer Inaktivität ablaufen — erzeugen Sie einen neuen.
Prüfen Sie die Instanz-URL — sie sollte wie https://marketplace.example.com aussehen, ohne angehängtes /api und ohne abschließenden Schrägstrich.
Prüfen Sie die Shop ID — bei den meisten Marktplätzen erforderlich. Die falsche Shop-ID aus einem Mehrshop-Verkäuferkonto zu kopieren, ist eine häufige Ursache.
Wenn Sie die Marktplatz-API durch ein internes Gateway leiten, stellen Sie sicher, dass der Authorization-Header unverändert weitergegeben wird.
Ein fehlgeschlagener Test setzt die Verbindung auf Status error und zeigt die Nachricht des Marktplatzes — fahren Sie mit dem Mauszeiger über den Status oder öffnen Sie den Dialog Verbindung bearbeiten, um sie zu sehen.

Fehler beim Produktexport

Häufige Meldungen und was Sie dagegen tun:

„Category not mapped” — öffnen Sie Mirakl → Quick Start → Kategorien, klicken Sie die Marktplatz-Kategorie, wechseln Sie auf den Reiter Mapping und fügen Sie die Shopware-Kategorie hinzu. Siehe Kategorien.
„Required attribute missing” — öffnen Sie Mirakl → Quick Start → Attributzuordnungen, suchen Sie das erforderliche Attribut und ordnen Sie es einem Shopware-Produktfeld, Eigenschaftsfeld oder einer Eigenschaftsgruppe zu.
„Invalid attribute value” — richten Sie auf der Attributzuordnung eine Wertumwandlung ein, die Ihren Shopware-Wert in einen vom Marktplatz akzeptierten umwandelt (Ersetzung, regulärer Ausdruck, Kleinschreibung, maximale Länge). Siehe Wertumwandlungen.
„Offer state unknown” — frischen Sie die Angebotsstatus auf der Seite Angebotsstatus auf (Mirakl-Status aktualisieren), setzen Sie dann einen Standard-Angebotsstatus im Dialog Verbindung bearbeiten oder überschreiben Sie ihn pro Produkt (siehe unten).

Sortieren Sie nach einem abgeschlossenen Export die Liste Produktkatalog nach Exportstatus = error, um zu sehen, welche Produkte fehlgeschlagen sind und warum.

Synchronisation hängt / kein Fortschritt

Stellen Sie sicher, dass der Hintergrundprozess (messenger:consume async) tatsächlich läuft.
Stellen Sie sicher, dass der Scheduler (scheduled-task:run) in Ihrem Cron läuft oder regelmäßig aufgerufen wird.
Die Drosselungs-Sperre gibt sich innerhalb einer Minute selbst frei — wenn ein Auftrag danach noch hängt, prüfen Sie die Tasks-Liste (Dashboard → Quick Start → Tasks) auf den Status und die letzte Nachricht.
Wenn eine Zeile in Sync Logs stundenlang im Status started steht, ohne dass eine Abschlusszeit gesetzt ist, ist der Hintergrundprozess während des Laufs gestorben. Öffnen Sie den Reiter Related Logs an der Zeile und sehen Sie sich die verlinkten API Logs-Einträge an, um zu sehen, wie weit der Marktplatz-Aufruf gekommen ist.
Bei rate-limitierten Handlern wird die Nachricht mit Verzögerung in die Warteschlange zurückgelegt — sie nimmt automatisch wieder Fahrt auf, sobald die Verzögerung abgelaufen ist. Siehe API-Drosselung.

Bestellimport liefert nichts, obwohl es neue Bestellungen gibt

Prüfen Sie das Anfangsdatum für Bestellimport an der Verbindung (Assistentenschritt 12) — beim ersten Lauf werden nur Bestellungen importiert, die nach diesem Datum aktualisiert wurden. Wenn Sie ein zukünftiges Datum eingegeben haben, liefert der erste Lauf nichts.
Nach dem ersten Lauf merkt sich das Plugin den Zeitstempel der zuletzt importierten Bestellung und setzt dort fort. Wenn die Uhren des Marktplatzes leicht abweichen, kann es zu einer kurzen Lücke kommen — der nächste geplante Lauf fängt sie ein.
Die Sync Logs-Zeile zum Lauf zeigt Processed = 0, wenn der Marktplatz eine leere Seite zurückgegeben hat. Öffnen Sie den verlinkten API Logs-Eintrag, um die tatsächliche Antwort zu sehen.
Prüfen Sie, dass Bestellimport aktivieren in Mirakl → Einstellungen → Synchronisierungseinstellungen an ist.

Rate-Limit-Meldungen in den Sync Logs

Das Plugin reagiert auf Rate Limits, indem es die Nachricht mit der vom Marktplatz geforderten Verzögerung erneut in die Warteschlange legt. Der eventuelle Abschluss ist garantiert, aber der Durchsatz sinkt.
Die plugin-eigene Minutenpause greift nur bei Produktimporten, Angebotsimporten und Bestandsimporten. Andere Synchronisationen (Bestellimport, Nachrichten-, Dokument-, Rechnungs-, Transaktionsprotokoll-Synchronisation) verlassen sich allein auf die Rate-Limit-Antwort des Marktplatzes.
Bei chronischen Rate-Limit-Meldungen auf den nicht verteilten Synchronisationen erhöhen Sie das entsprechende Intervall unter Mirakl → Einstellungen → Synchronisierungseinstellungen.
Teilen Sie keinen API-Schlüssel zwischen zwei Shopware-Instanzen — jede Instanz verteilt ihre eigenen Aufrufe, aber der Marktplatz zählt die kombinierte Last. Verwenden Sie eine Instanz pro Verkäuferkonto.

Das vollständige Bild finden Sie unter API-Drosselung.

Angebot aktualisiert sich auf dem Marktplatz nach einer Shopware-Änderung nicht

Öffnen Sie die Seite Angebotszuordnungen und prüfen Sie den Sync-Status des Angebots. Damit die Änderung übernommen wird, sollte er Queued oder Retry sein.
Steht er auf Synced, geht das Plugin davon aus, dass sich seit der letzten Synchronisation nichts geändert hat — unveränderte Uploads werden übersprungen. Erzwingen Sie eine erneute Synchronisation über das Dashboard → Verbindungskarte → Alle Angebote synchronisieren.
Steht er auf Error, ist der letzte Fehler an der Zeile sichtbar — meist hat eine Kategorieänderung das Angebot für die aktuelle Marktplatz-Kategorie ungültig gemacht oder ein erforderliches Angebotsfeld fehlt jetzt.
Reine Bestandsänderungen übernimmt die Aufgabe Bestandssynchronisation im 15-Minuten-Intervall sowie die sofortige Änderungsmeldung — sie beeinflussen den Vollangebotsstatus nicht.

Nachrichten- / Dokument- / Rechnungs- / Transaktionsprotokoll-Synchronisation ist inaktiv

Diese fünf (Nachrichtensynchronisierung aktivieren, Bestelldokument-Synchronisierung aktivieren, Dokumentanforderungs-Synchronisierung aktivieren, Rechnungssynchronisierung aktivieren, Transaktionsprotokoll-Synchronisierung aktivieren) sind standardmäßig aus. Schalten Sie sie nach Bedarf in Mirakl → Einstellungen → Synchronisierungseinstellungen ein.
Nach dem Einschalten läuft die anfängliche Historie einmal nach. Beobachten Sie die Sync Logs für den Fortschritt — wird der Lauf unterbrochen, merkt sich der Cursor seine Position und der nächste geplante Lauf setzt von dort fort.

Datenbank wächst zu schnell

API-Protokoll — jeder Marktplatz-Aufruf ist eine Zeile mit vollständiger Anfrage und Antwort. API-Protokoll-Aufräumung entfernt Zeilen, die älter sind als API-Protokoll-Aufbewahrung (Tage) (Standard 30).
Synchronisationsprotokoll — jeder langlaufende Lauf und jedes einmalige Ereignis schreibt eine Zeile (sofern die Stufe nicht abgewählt ist). Synchronisationsprotokoll-Aufräumung entfernt Zeilen, die älter sind als Synchronisierungsprotokoll-Aufbewahrung (Tage) (Standard 30).
Aufgabenfortschritt — Aufgaben-Aufräumung entfernt einmal pro Tag abgeschlossene Einträge.
Exporteinträge — Export-Aufräumung entfernt einmal pro Stunde abgeschlossene Produktexport-Zeilen und die erzeugten CSV-Dateien.
Transaktionsprotokoll — Finanzdaten, ohne automatische Aufbewahrung. Archivieren Sie sie in einen separaten Speicher, wenn Ihr DB-Größenbudget ausgereizt ist.

Wenn Sie unkontrolliertes Wachstum sehen, prüfen Sie, dass der Scheduler läuft — ohne ihn wird keine der Aufräumaufgaben ausgeführt.

Wo Sie zuerst nachsehen

Sync Logs (Dashboard → Quick Start → Logs) — hochgradig „was versucht, verarbeitet, fehlgeschlagen wurde”.
API Logs (Quick Start → API Logs) — der rohe HTTP-Aufruf mit vollständiger Anfrage und Antwort, filterbar nach Datum, Verbindung und Typ.
Tasks (Quick Start → Tasks) — für aus dem Admin gestartete Aufgaben: Prozentsatz, letzte Nachricht.
Imports (Quick Start → Imports) und Produktexporte (Quick Start → Produktexporte) — marktplatzseitige Importaufträge mit Status und Zeilenfehlern.

Wenn Sie die Ursache trotzdem nicht finden, ist der API Logs-Eintrag zum fehlgeschlagenen Aufruf das Artefakt, das Sie mit dem Support teilen.