Haeufige Fehler

Ein Playbook fuer die konkreten Fehler, auf die Redakteure und Admins am haeufigsten stossen. Jeder Eintrag folgt demselben Muster: Symptom (was du siehst), Ursache (was es technisch ist), Loesung (was du tust). Arbeite die Schritte der Reihe nach ab — der erste Schritt ist die wahrscheinlichste Ursache.

1. Widget erscheint nicht im Frontend

Symptom: Ein Widget ist auf der Seite platziert, der Pagebuilder zeigt es in der Vorschau, aber die Live-Seite rendert eine leere Zeile.

Ursache: Das Widget ist durch ein Responsive-Visibility-Flag versteckt, oder die Seite ist nicht publiziert.

Loesung:

1. Oeffne das Widget im Pagebuilder und pruef die Sichtbarkeit-Sektion. Bestaetige, dass mindestens Desktop, Tablet oder Mobile aktiv ist. Sind alle drei aus, ist das Widget auf jedem Breakpoint versteckt.
2. Bestaetige, dass die Seite selbst publiziert ist — die Top-Bar darf kein DRAFT-Badge zeigen. Wenn doch, klick auf Veröffentlichen.
3. Leer den API-Cache unter Administration → Cache → Cache leeren.

2. Shopware-6-Kategorien sind leer

Symptom: Das Kategorie-Teaser-Widget oder das SW6-Menue rendert ohne Kategorien. Eine Browser-Konsolen-Meldung sagt evtl. SW6: empty root_category_id response oder circuit breaker open.

Ursache: Die Shopware-Verbindung ist falsch konfiguriert, der Access-Key wurde rotiert, oder die Root-Category-ID des Sales Channels ist falsch.

Loesung:

1. Oeffne E-Commerce → Shopware 6 → Verbindung und klick auf Verbindung testen. Eine rote Lampe heisst, die Zugangsdaten werden abgelehnt — stell den Access-Key im Shopware-Admin neu aus und trag ihn ein.
2. Pruef Sales Channel ID und Root Category ID. Beide UUIDs kommen aus dem Shopware-Admin unter Vertriebskanäle → {dein Kanal}. Ein Tippfehler hier liefert einen leeren Kategorie-Baum.
3. Ist der Circuit Breaker offen, warte 60 Sekunden oder klick auf Circuit Breaker zurücksetzen auf der Verbindungs-Seite. Der Breaker oeffnet nach 5 aufeinanderfolgenden API-Fehlern und schliesst sich nach der Abkuehlzeit automatisch.
4. Loese eine Kategorie-Synchronisation manuell unter E-Commerce → Shopware 6 → Kategorien → Jetzt synchronisieren aus.

3. Sitemap ist nicht aktuell

Symptom: Seiten, die gestern publiziert wurden, erscheinen noch nicht in /sitemap.xml. Suchmaschinen indizieren weiter alte URLs.

Ursache: Der Scheduled-Sitemap-Task haengt, ist deaktiviert, oder ist nie gelaufen.

Loesung:

1. Oeffne Administration → Task Manager → Geplante Tasks. Suche Sitemap-Generierung und pruef Letzter Lauf — sollte innerhalb von 24 Stunden liegen.
2. Ist der Task deaktiviert, schalt ihn an.
3. Ist der Task aktiv, aber nicht gelaufen, klick auf Jetzt ausfuehren. Schau im Queue-Tab nach Fehlern.
4. Fuer Shopware-6-Inhalte pruef, ob sw6_config → last_sync aktuell ist. Veraltete SW6-Daten landen nicht in der Sitemap.
5. Leer den API-Cache; der Sitemap-Endpunkt selbst ist 1 Stunde gecached.

4. Pagebuilder laedt endlos

Symptom: Eine Seite im Pagebuilder zu oeffnen zeigt minutenlang den Lade-Spinner. Keine Fehler-Meldung, kein Strukturbaum.

Ursache: Ein korrupter Entwurf blockiert den Snapshot-Load, der Browser-Cache haelt veraltetes JS, oder APCu ist leer und der erste Load baut die Kataloge neu auf.

Loesung:

1. Hartes Neuladen mit Ctrl+F5 / Cmd+Shift+R, um den Browser-Cache zu umgehen.
2. Haengt der Spinner weiter, oeffne die Browser-Konsole und schau nach einem 500-Fehler auf /api/backend/pagebuilder. Ein 500 deutet meist auf einen korrupten page_versions-Eintrag.
3. Oeffne Versionen auf der Seite. Hat der neueste Entwurf einen seltsamen Zeitstempel oder einen (corrupt)-Marker, loesch ihn — der Pagebuilder faellt auf die vorherige veroeffentlichte Version zurueck.
4. Ist APCu leer, baut der erste Pagebuilder-Aufruf den Widget-Katalog auf und braucht 10-30 Sekunden. Folgeaufrufe sind schnell.

5. Email-Marketing-Verbindungstest schlaegt fehl

Symptom: Der Verbindung testen-Button auf einer Email-Marketing-Verbindung liefert einen Fehler: 401 Unauthorized, 403 Forbidden oder invalid API key.

Ursache: Falscher API-Key, fehlende Data-Center-Endung (Mailchimp) oder widerrufene Zugangsdaten.

Loesung:

1. Mailchimp: Der API-Key muss die Data-Center-Endung enthalten (-us21, -us5, etc.). Ohne sie liefern alle Aufrufe 401.
2. Brevo: Generier den Key in Brevo → SMTP & API → API Keys neu. Alte Keys werden nach Provider-Wartung manchmal stillschweigend ungueltig.
3. Rapidmail: Der Provider nutzt Basic Auth — bestaetige, dass Benutzer- und Passwort-Feld gefuellt sind.
4. Klaviyo: Der Key muss Full-Access-Berechtigung haben. Ein Read-Only-Key kann keine Benutzer eintragen.
5. Fuer Double-Opt-In-Ablaeufe bestaetige, dass eine DOI-Template-ID am Formular konfiguriert ist — nicht nur an der Verbindung.

6. Stripe- oder PayPal-Zahlung scheitert

Symptom: Im Checkout klickt der Benutzer auf Bezahlen und bekommt einen Fehler — Zahlung konnte nicht abgeschlossen werden, Bestellung konnte nicht angelegt werden oder ein stiller Sprung zurueck in den Warenkorb.

Ursache: Webhooks sind nicht registriert, ein Dev-Sandbox-Schluessel wird im Produktivbetrieb eingesetzt, oder die Bestellung wurde erstellt, aber die Zahlungs-Erfassung kam nie zurueck.

Loesung:

1. Oeffne E-Commerce → Zahlungsanbieter → Stripe (oder PayPal). Bestaetige, dass die Schluessel Live/Production-Schluessel sind, keine Test/Sandbox.
2. Fuer Stripe: Der Webhook-Endpunkt muss im Stripe-Dashboard registriert sein und auf https://{deine-seite}/api/shop/stripe/webhook zeigen. Ohne ihn wirken Zahlungen erfolgreich, die Bestellung bleibt aber im Status pending.
3. Fuer PayPal: Bestaetige, dass Rueckkehr-URL und Abbruch-URL beide HTTPS sind und zur Produktiv-Domain passen.
4. Pruef Log → Filter: Zahlung fuer den genauen Fehler. Karten-Ablehnungen und Betrugs-Sperren hinterlassen klare Eintraege.
5. Scheitern Zahlungen nur in bestimmten Laendern, pruef die Waehrungs- und Regional-Einstellungen im Provider-Dashboard — manche Methoden sind geografisch eingeschraenkt.

7. Seite leitet endlos um

Symptom: Eine Seite im Browser zu oeffnen laeuft in einer Endlosschleife. Der Browser zeigt irgendwann ERR_TOO_MANY_REDIRECTS.

Ursache: Ein 301-Weiterleitungs-Eintrag zeigt auf sich selbst oder auf eine andere URL, die zurueckleitet.

Loesung:

1. Oeffne SEO & Design → Weiterleitungen. Such nach dem Seiten-Slug in den Spalten Von und Nach.
2. Loesch jeden Eintrag, bei dem Von und Nach (direkt oder transitiv) auf dieselbe URL aufloesen.
3. Bestaetige, dass kein url_rewrite-Eintrag mit einer Weiterleitung fuer denselben Slug kollidiert — das Rewrite gewinnt, aber wenn das Rewrite-Ziel selbst eine Weiterleitung hat, entsteht eine Schleife.
4. Leer den API-Cache, um zwischengespeicherte Weiterleitungs-Antworten zu verwerfen.

8. Upload scheitert mit Fehler 413

Symptom: Ein grosses Bild oder Video im Media Manager hochzuladen liefert 413 Payload Too Large oder Request Entity Too Large. Kleine Dateien laden einwandfrei hoch.

Ursache: PHP oder der Webserver blockiert die Upload-Groesse. Drei Limits stapeln sich: PHP upload_max_filesize, PHP post_max_size und das Body-Limit des Webservers (client_max_body_size bei nginx, LimitRequestBody bei Apache).

Loesung:

1. Bitte deinen Hoster oder Server-Admin, alle drei Limits zu erhoehen. Ein haeufiger sicherer Satz ist upload_max_filesize=128M, post_max_size=130M, client_max_body_size=150M.
2. Starte PHP-FPM (oder Apache) nach der Aenderung neu.
3. Das Backend zeigt das wirksame Limit unter Administration → Allgemeine Einstellungen → Upload-Limit. Aendert sich der Wert nach der Anpassung nicht, hast du die falsche php.ini editiert — pruef phpinfo() auf den aktiven Pfad.
4. Fuer Videos erwaege, auf einen externen Host (Vimeo, YouTube, S3) zu verlinken statt ueber das Backend hochzuladen.

9. Canonical-URL zeigt auf die falsche Kategorie

Symptom: Google Search Console meldet die falsche Canonical-URL fuer ein Shopware-6-Produkt. Das Produkt liegt in mehreren Kategorien, und die Canonical zeigt auf die "falsche".

Ursache: Das Canonical-Kategorie-Kennzeichen ist nicht gesetzt, also waehlt das System die erste Kategorie alphabetisch.

Loesung:

1. Oeffne E-Commerce → Shopware 6 → Kategorien. Suche die Kategorie, die fuer das Produkt canonical sein soll.
2. Schalt Als kanonische Kategorie verwenden an.
3. Bau den Produkt-Cache unter Shopware 6 → Produkte → Cache neu aufbauen neu auf. Die neue Canonical erscheint in <link rel="canonical"> nach der naechsten Seitenausgabe.
4. Liegt das Produkt in mehreren canonical-markierten Kategorien, gewinnt die erste nach sort_order.

10. User-Center-Eintrag erscheint nicht

Symptom: Ein Plugin verspricht, einen Eintrag im Shop-Benutzer-Konto anzulegen (z.B. Meine Kurse, Meine Zertifikate), aber die Konto-Seite zeigt ihn nicht.

Ursache: Das Plugin ist nicht installiert, oder der angemeldete Benutzer erfuellt die isVisible()-Bedingung nicht, die das Plugin registriert hat.

Loesung:

1. Oeffne Administration → Plugin Manager und bestaetige, dass das Plugin Installiert und Aktiv ist.
2. Melde dich als End-Benutzer an (nicht als Backend-Admin). User-Center-Eintraege rendern auf der Frontend-Konto-Seite, nicht im Backend.
3. Manche Eintraege verstecken sich, bis der Benutzer relevante Daten hat — z.B. Meine Kurse ist leer, wenn der Benutzer keine Kurse gekauft hat. Kauf einen Test-Kurs oder leg Seed-Daten an.
4. Hartes Neuladen im Frontend, um zwischengespeicherte JS-Bundles zu verwerfen.

11. Media Manager zeigt keine Dateien

Symptom: Der Media Manager oeffnet sich, aber das Raster ist leer, obwohl du weisst, dass Dateien existieren.

Ursache: Ein aktiver Ordner-Filter, ein Berechtigungs-Filter oder ein Dateiname mit Sonderzeichen, die den Datei-Scan brechen.

Loesung:

1. Klick auf Alle Ordner oben im Ordnerbaum, um den aktuellen Filter zu loeschen.
2. Leer das Suchfeld — ein veralteter Filter aus einer frueheren Sitzung bleibt im localStorage erhalten.
3. Sieht der Ordner weiter leer aus, obwohl Dateien auf der Platte liegen, verbind dich per SFTP und pruef, ob Dateinamen ?, # oder Steuerzeichen enthalten. Nenn sie in ASCII-sichere Slugs um.
4. Fuehr Administration → Task Manager → Medien neu einlesen aus, um den Datei-Index neu aufzubauen.

12. AI-Prompt liefert nichts

Symptom: In einem AI-Feld (SEO-Text, Blog-Umschreibung, Layout-Generierung) laeuft der Spinner eine Weile, dann kommt leer zurueck oder eine Fehlermeldung sagt AI request failed.

Ursache: Die AI-Verbindung ist inaktiv, der API-Key ist abgelaufen, oder ein Rate-Limit hat gegriffen.

Loesung:

1. Oeffne SEO & Design → AI Textgenerierung → Verbindungen. Die aktive Verbindung muss eine gruene Lampe haben.
2. Klick auf Verbindung testen — eine rote Lampe mit 401 heisst, der Key ist widerrufen. Generier im Provider-Dashboard (OpenAI, Anthropic, Google, Mistral) neu und trag ihn ein.
3. Pruef die Nutzungs-/Abrechnungs-Seite des Providers. Aufgebrauchte Credits oder ueberschrittene Kontingente liefern 429; das Backend zeigt das als allgemeinen Fehler.
4. Fuer lange Ausgaben (Layout-Generierung, langer Blog-Text) kann die Anfrage 30-60 Sekunden dauern. Warte ueber den anfaenglichen Spinner hinaus — das Backend fragt bis zu 5 Minuten, bevor es aufgibt.
5. Wenn die Verbindung funktioniert, aber ein bestimmtes Feature fehlschlaegt, oeffne AI-Features-Referenz und bestaetige, dass das Feature einer Verbindung mit der richtigen Faehigkeit zugeordnet ist (Vision, JSON-Modus).

13. Sitemap enthaelt geloeschte Seiten

Symptom: /sitemap.xml listet Seiten, die vor Wochen geloescht wurden. Suchmaschinen rufen 404s ab.

Ursache: Die Seite wurde geloescht, aber der Sitemap-Task lief vor dem Festschreiben der Loeschung, oder eine 301-Weiterleitung haelt die URL in der Task-Ausgabe am Leben.

Loesung:

1. Loese einen frischen Sitemap-Lauf unter Administration → Task Manager → Geplante Tasks → Sitemap-Generierung → Jetzt ausfuehren aus.
2. Pruef SEO & Design → Weiterleitungen auf eine veraltete Weiterleitung, die auf den geloeschten Slug zeigt. Eine Weiterleitung haelt die Quell-URL als Ursprung in der Sitemap.
3. Hatte die geloeschte Seite Unterseiten, stell die Elternseite kurz wieder her, loesch die Kinder explizit, und loesch die Elternseite nochmal. Verwaiste Kinder hinterlassen manchmal Geister-Eintraege.

14. Cache-Leeren hat keinen Effekt

Symptom: Du hast auf Cache leeren geklickt, eine Erfolgsmeldung erschien, aber das Frontend liefert weiter den alten Inhalt.

Ursache: Eine zweite Cache-Schicht ist im Spiel — CDN, nginx-Proxy-Cache oder Browser-Cache. Das Backend leert nur seinen eigenen APCu-Antwort-Cache.

Loesung:

1. Hartes Neuladen mit Ctrl+F5 / Cmd+Shift+R.
2. Sitzt ein CDN davor (Cloudflare, Fastly, CloudFront), leer es aus dem CDN-Dashboard. Dein Hoster bietet dafuer evtl. einen Wrapper.
3. Bei nginx-gecachten Setups muss fastcgi_cache_purge eingerichtet sein — frag deinen Server-Admin, ob es das ist. PHP-FPM-Neustart leert den nginx-Cache NICHT.
4. Fuer Custom-CSS-Aenderungen fuehr zusaetzlich CSS neu kompilieren aus — Custom CSS liegt in einer separaten kompilierten Datei.

15. Geplante Veroeffentlichung ist nicht live gegangen

Symptom: Ein Entwurf war fuer 10:00 geplant, aber um 10:15 zeigt die Seite noch die alte Version. Kein sichtbarer Fehler.

Ursache: Der Worker fuer geplante Tasks laeuft nicht, die Server-Uhr ist abgedriftet, oder der Entwurf wurde zwischen Planung und Veroeffentlichungs-Zeit ungueltig.

Loesung:

1. Oeffne Administration → Task Manager → Geplante Tasks. Geplante Seiten veroeffentlichen muss einen aktuellen Letzten Lauf zeigen (innerhalb von 5 Minuten). Ist er veraltet, laeuft der Worker nicht — kontaktier deinen Hoster.
2. Pruef die Server-Zeit: Administration → Allgemeine Einstellungen → Server-Zeit. Driftet sie um mehr als eine Minute, feuern die Plaene zur falschen Wanduhr-Zeit.
3. Oeffne die Seite im Pagebuilder. Hat der Entwurf einen Validierungsfehler (kaputtes Widget, fehlendes Pflichtfeld), kann er nicht automatisch veroeffentlicht werden. Der Task protokolliert das Ueberspringen unter Log → Filter: Geplante Veroeffentlichung.
4. Plan die Veroeffentlichung manuell neu, um zu testen.

Siehe auch

• FAQ — kurze Fragen und Antworten fuer alltaegliche Fragen
• Glossar — Begriffs-Referenz
• Task Manager — Diagnose fuer Queue und geplante Tasks
• Cache — API-Antwort-Cache und CSS-Cache leeren
• Log — System-Log-Eintraege filtern