Seite kopieren

Fehlersuche

Zuletzt geändert am 9. Oktober 2026

Was im OSPO-Projekt schiefging, woran es lag und was geholfen hat. Gesucht wird nach dem, was man sieht. Die Hintergründe stehen jeweils auf der verlinkten Seite.

Docker und Container

Eine geänderte Datei kommt im Container nicht an

Ursache: Die Datei ist einzeln eingehängt, und das Werkzeug auf dem Host hat sie durch eine neue ersetzt (mv, sed -i, viele Editoren). Der Container hängt weiter an der alten Inode.

Abhilfe: Solche Dateien an Ort und Stelle überschreiben, danach docker restart. md5sum auf Host und im Container zeigt, ob beide denselben Stand sehen. Siehe Betrieb.

An der Stelle einer Datei liegt im Container ein Verzeichnis

Ursache: Die Datei fehlte auf dem Host, als der Container startete. Docker legt dann ein leeres Verzeichnis mit ihrem Namen an.

Abhilfe: Container stoppen, das Verzeichnis auf dem Host löschen, die Datei anlegen, Container neu erstellen.

WP-CLI ist nach docker compose up -d verschwunden

Ursache: Es wurde nachträglich in den laufenden Container installiert. Ein neu erstellter Container startet wieder vom Image.

Abhilfe: WP-CLI ins Image aufnehmen, siehe Betrieb.

Elasticsearch startet immer wieder neu, im Log steht AccessDeniedException

Ursache: Elasticsearch läuft im Container unter der Kennung 1000, das Datenverzeichnis gehört jemand anderem. Ein frisch angelegtes Volume gehört root.

Abhilfe: chown -R 1000:1000 auf das Datenverzeichnis.

Ein Skript endet nach docker compose run einfach, ohne Fehler

Ursache: Das Skript läuft per Pipe oder Heredoc, etwa über ssh auf einem anderen Rechner. docker compose run liest die Standardeingabe mit und verschluckt dabei den Rest des Skripts.

Abhilfe: docker compose run -T verwenden und die Standardeingabe des Befehls auf /dev/null umlenken. Die Einrichtung im Paket umgeht das, indem sie setup.sh erst in eine Datei schreibt und dann ausführt.

Ein Port ist von außen erreichbar, obwohl die Firewall ihn sperrt

Ursache: Docker veröffentlicht Ports auf allen Schnittstellen und trägt seine Regeln an der Firewall vorbei ein, ufw greift nicht.

Abhilfe: Ports in der docker-compose.yml an 127.0.0.1 binden (127.0.0.1:8081:80), dann erreicht sie nur der Reverse Proxy. Siehe Randsysteme erreichen.

WordPress und WooCommerce

WP-CLI meldet „'wc' is not a registered wp command“

Ursache: WooCommerce ist deaktiviert, etwa nach einem Update außerhalb von WP-Cron (nächster Punkt).

Abhilfe: wp plugin activate woocommerce, danach wp wc update. Siehe Betrieb.

Nach einem Update sind Plugins deaktiviert

Ursache: Der Updater wurde außerhalb von WP-Cron aufgerufen, zum Beispiel per wp eval-file. WordPress aktiviert Plugins nach dem Update nur dann wieder, wenn wp_doing_cron() wahr ist.

Abhilfe: Plugins wieder aktivieren und Updates von Hand nur noch mit wp cron event run wp_maybe_auto_update anstoßen. Siehe Betrieb.

Automatische Updates kommen nicht

Ursache: Eine von drei Möglichkeiten:

• DISABLE_WP_CRON ist gesetzt, und kein System-Cron springt ein.
• Das Ereignis wp_maybe_auto_update fehlt im Cron.
• Bei Paketen aus dem Konfigurations-Assistenten wurde die Karte „Automatisch aktualisieren“ abgewählt.

Abhilfe: wp cron event list zeigt, ob das Ereignis da ist und wann es zuletzt lief. wp plugin auto-updates status --all zeigt, für welche Plugins Updates eingeschaltet sind. Siehe Betrieb und Erweiterungen im Assistenten.

WooCommerce bleibt auf der alten Hauptversion stehen

Ursache: Gewollt. WooCommerce blockiert automatische Updates über eine Hauptversion hinweg, weil sie eine Datenbankmigration brauchen.

Abhilfe: Von Hand aktualisieren, danach wp wc update. Siehe Betrieb.

Ein remove_action() im Child Theme wirkt nicht

Ursache: Die functions.php des Child Themes lädt vor der des Parent Themes. Zum Zeitpunkt des Aufrufs hat Storefront seine Hooks noch gar nicht registriert.

Abhilfe: Alle Hook-Änderungen in eine Funktion an init legen. Siehe Theme und Frontend.

Eine lange Überschrift oder ein Bild sprengt das Spaltenlayout

Ursache: Flex-Elemente haben ein implizites min-width: auto, das sich am Inhalt orientiert.

Abhilfe: min-width: 0 auf das Flex-Element. Weitere Fälle unter CSS-Fallstricke.

Mailversand

Bestellbestätigungen und Formulare kommen nicht an, ohne Fehlermeldung

Ursache: Das WordPress-Image enthält keinen Mailserver, /usr/sbin/sendmail fehlt. PHP meldet den Fehlschlag nicht.

Abhilfe: Über WP Mail SMTP an einen SMTP-Dienst senden. Siehe Mailversand.

Das Relay antwortet 454 4.7.0 Temporary authentication failure

Ursache: Nicht unbedingt falsche Zugangsdaten. Im OSPO-Projekt hatte der SPF-Eintrag der Absenderdomain mehr als zehn DNS-Abfragen, bei DMARC mit p=reject lehnt das Relay die Anmeldung dann vorsorglich ab.

Abhilfe: Zuerst SPF und DMARC der Absenderdomain prüfen, dann die Zugangsdaten. Siehe Mailversand.

Das Relay antwortet 450 4.7.1 Monthly message limit exceeded

Ursache: Das Monatskontingent des SMTP-Kontos ist aufgebraucht. Zugangsdaten und DNS sind in Ordnung.

Abhilfe: Kontingent beim Anbieter prüfen oder erhöhen. Abgelehnte Mails schickt WordPress nicht noch einmal. Welche Empfänger betroffen waren, zeigen die Debug-Ereignisse von WP Mail SMTP.

Randsysteme

Eine API antwortet 401 als reiner Text statt als JSON

Ursache: Nicht die Anwendung lehnt ab, sondern der Reverse Proxy mit seiner Basic-Auth.

Abhilfe: Eine Ausnahme ohne Auth für genau die Pfade der API, siehe Basic-Auth und Server-zu-Server-Verkehr.

Die Matomo-API antwortet 401, obwohl die Ausnahme eingerichtet ist

Ursache: Die Ausnahme greift nur, wenn module=API in der Adresse steht. Ein POST auf /index.php, das module nur im Formularinhalt mitschickt, landet beim Router mit Auth.

Abhilfe: module=API und die Methode in die Adresse, den Token in den Inhalt der Anfrage. So fragt auch das Plugin an. Siehe Matomo.

Matomo zählt keine Besuche

Ursache: Meist eine von zwei Einstellungen. track_mode steht ab Werk auf disabled. Oder die Einstellungen wurden als ein gemeinsames Objekt geschrieben, wp-piwik erwartet aber jede als eigene Option.

Abhilfe: wp option get wp-piwik_global-track_mode prüfen, die Optionen einzeln setzen. Siehe Matomo.

Der LibrePIM-Import bricht beim Blättern ab

Ursache: LibrePIM steht hinter einem Reverse Proxy und erzeugt in der Pagination http://-Links. Der PHP-Client folgt dem Redirect nicht.

Abhilfe: Drei Stellen in LibrePIM: TRUSTED_PROXY_IPS, clear_env = no im FPM-Pool und fastcgi_param HTTP_X_FORWARDED_PROTO. Siehe LibrePIM.

Der Import überspringt ein Produkt, obwohl sich etwas geändert hat

Ursache: Der Connector vergleicht nur die Daten aus dem PIM, über das Postmeta _akeneo_hash. Eine Änderung auf WordPress-Seite, etwa ein neues Mapping, sieht er nicht.

Abhilfe: _akeneo_hash des Produkts löschen und neu importieren. Siehe LibrePIM.

Nach einem Import stimmt der Bestand im Shop nicht mehr

Ursache: Der Bestand ist im PIM gepflegt und gemappt, und die Daten fließen nur vom PIM in den Shop. Verkäufe senken den Bestand im Shop, der nächste Import setzt ihn auf den Wert aus dem PIM zurück. Auf der Sandbox sprang ein Produkt so von 23 auf 25.

Abhilfe: Den Bestand nur an einer Stelle führen. Entweder im Shop, dann das Mapping für den Bestand entfernen, oder im PIM, dann braucht es einen Rückweg der Verkäufe ins PIM, den der Connector nicht kennt. Siehe LibrePIM.

Ein Import holt die Kategorien eines anderen Shops

Ursache: Mehrere Shops teilen sich eine LibrePIM-Instanz, und der Import läuft über einen fremden Kanal.

Abhilfe: Je Shop ein eigener Kanal mit eigenem Kategoriebaum. Siehe LibrePIM.

Die LibrePIM-API antwortet 422 beim Anlegen eines Zahlen-Attributs

Ursache: Das Feld negative_allowed fehlt.

Abhilfe: negative_allowed mitschicken. Siehe LibrePIM.

Webhook-Adressen in Activepieces zeigen auf localhost

Ursache: Activepieces baut sie aus AP_FRONTEND_URL, im Paket aus dem Assistenten aus ACTIVEPIECES_FRONTEND_URL.

Abhilfe: Dort die öffentliche Adresse eintragen und den Container neu erstellen. Siehe Activepieces.

Activepieces fragt im Browser immer wieder nach der Anmeldung

Ursache: Basic-Auth vor Activepieces. Die Socket.IO-Verbindungen und Hintergrundabfragen geraten damit in eine Anmeldeschleife.

Abhilfe: Activepieces ohne Basic-Auth betreiben, den Schutz übernimmt das eigene Login.

Ein neues Produkt kommt erst Minuten später in Activepieces an

Ursache: Kein Fehler. WooCommerce stellt Webhooks über den Action Scheduler zu, also mit dem nächsten Lauf von WP-Cron.

Abhilfe: Keine nötig. Beim Testen wp action-scheduler run anstoßen statt zu warten.

Ein Test-Webhook liefert einen Flow ohne Produktdaten

Ursache: WooCommerce stellt die Zustellung erst am Ende des PHP-Laufs in die Warteschlange und baut den Inhalt erst beim Zustellen. Wer in einem Testskript ein Produkt anlegt, die Zustellung sofort anstößt und das Produkt danach löscht, schickt einen Webhook ohne Produkt. Activepieces bricht dann beim Zurückschreiben mit 404 rest_no_route ab.

Abhilfe: Das Testprodukt stehen lassen, bis der Flow durchgelaufen ist, und erst danach löschen.

Eine Variable im Activepieces-Flow ist leer

Ursache: Der Ausdruck wurde von Hand getippt. {{schritt.feld}} ohne Data Selector wird nicht als Bindung erkannt und löst still zu einem Leerstring auf.

Abhilfe: Variablen nur über den Data Selector einfügen. Siehe Activepieces.

Eine Marke, per REST-API mitgeschickt, kommt nicht an

Ursache: Die Produkt-API von WooCommerce speichert beim Schreiben nur categories und tags, brands ignoriert sie still.

Abhilfe: Ein eigener Endpunkt, siehe Activepieces.

KI-Produkttexte

Der Generator meldet „ChatGPT API key is not configured“

Ursache: Das Plugin kennt im Code nur OpenAI, Google und Anthropic. Ein Ollama-Anbieter erscheint zwar in der Auswahl, wird aber nicht benutzt.

Abhilfe: Platzhalter-Schlüssel für OpenAI setzen und die Anfrage per Must-Use-Plugin auf Ollama umleiten. Siehe KI-Produkttexte.

Das Abzeichen „Mit KI generiert“ fehlt

Ursache: Das Plugin setzt das Meta _wtofe_ai_generated nur über den Schalter in der Metabox, auch nicht über den eigenen Generieren-Knopf.

Abhilfe: Wer Texte über die REST-API schreibt, setzt das Meta im selben Request. Siehe KI-Kennzeichnung.

Pakete aus dem Konfigurations-Assistenten

Die Einrichtung bricht sofort mit „ADMIN_EMAIL ist leer“ ab

Ursache: In der .env fehlt die E-Mail-Adresse für die Verwaltung.

Abhilfe: ADMIN_EMAIL eintragen und die Einrichtung erneut starten. Die SMTP-Werte dürfen dabei leer bleiben. Siehe Paket starten.

Am Ende der Einrichtung steht „Nicht geklappt hat: …“

Ursache: Einzelne Schritte, meist eine Erweiterung, die gerade nicht erreichbar war. Die Einrichtung bricht deshalb nicht ab, sondern sammelt die Fehlschläge.

Abhilfe: Die genannten Punkte von Hand nacharbeiten oder die Einrichtung erneut starten, sie lässt sich gefahrlos wiederholen.

Besucher sehen statt des Shops nur eine Ankündigungsseite

Ursache: Gewollt. Der Shop bleibt gesperrt, bis Impressum, AGB, Datenschutzerklärung und Widerrufsbelehrung geprüft sind.

Abhilfe: Nach der Prüfung wp option update woocommerce_coming_soon no. Siehe Paket starten.