Dokumentation · Fehlerbehebung

Bild-Importfehler

Dieses Dokument behandelt Fehler, die auftreten können, wenn das Plugin Fahrzeugbilder von der AutoScout24-API herunterlädt und anhängt. Es beschreibt wahrscheinliche Ursachen sowie die Schritte zur Diagnose und Behebung von Medienimportproblemen.

Wann Sie dieses Dokument verwenden sollten

Lesen Sie dieses Dokument, wenn:

Fahrzeug-Beiträge importiert werden, aber keine Bilder oder nur ein Teil der Bilder vorhanden sind.
Das Plugin-Protokoll Zeilen enthält, die Image download failed oder media_handle_sideload failed erwähnen.
Das Beitragsbild (Featured Image) bei importierten Fahrzeug-Beiträgen fehlt.
Die WebP-Konvertierung aktiviert ist, Bilder aber in ihrem Originalformat gespeichert werden.
Der Image-Queue-Worker gelaufen ist, aber immer noch Bilder fehlen.

Übersicht

Wenn das Plugin ein Fahrzeug importiert, lädt es Bilder von den URLs herunter, die von der AutoScout24-API bereitgestellt werden, und hängt sie an den WordPress-Beitrag an. Der Prozess verwendet die in WordPress integrierten Funktionen download_url() und media_handle_sideload(), die Bilder im standardmäßigen WordPress-Uploads-Verzeichnis ablegen, Vorschaubilder generieren und den Anhang in der Mediathek registrieren.

Deduplizierung

Vor dem Herunterladen eines Bildes prüft das Plugin, ob es bereits importiert wurde, indem es nach einem Anhang mit einem passenden _as24ci_source_url-Post-Meta-Wert sucht. Wenn eine Übereinstimmung gefunden wird, wird die vorhandene Anhangs-ID wiederverwendet und es erfolgt kein Download. Dies verhindert, dass dasselbe Bild mehrfach gespeichert wird.

Beitragsbild

Das erste Bild im Set wird automatisch als Beitragsbild (Post-Thumbnail) festgelegt, sofern dem Beitrag nicht bereits ein Beitragsbild zugewiesen ist. Nachfolgende Bilder werden im _as24ci_image_ids-Post-Meta-Array erfasst.

Bild-Warteschlangen-Modus (Image Queue Mode)

Wenn der Bild-Warteschlangen-Modus aktiviert ist (Standardeinstellung für Cron- und REST-Importläufe), wird während des Importlaufs nur das erste Bild pro Fahrzeug sofort heruntergeladen. Die verbleibenden Bild-URLs werden in eine persistente Warteschlange gestellt. Ein separater WP-Cron-Worker (as24ci_image_queue_process) verarbeitet diese Warteschlange asynchron in Batches von 30 Bildern pro Durchlauf. Dies reduziert die pro Importlauf benötigte Zeit und den Speicherbedarf.

Siehe Cron-Jobs und Hintergrundverarbeitung für Anleitungen zur Diagnose von Fehlern des Image-Queue-Workers.

WebP-Konvertierung

Wenn die WebP-Konvertierung aktiviert ist, wird jedes heruntergeladene Bild in das .webp-Format konvertiert, bevor es an die WordPress-Mediathek übergeben wird. Das Plugin versucht die Konvertierung zuerst mit PHP GD (imagewebp) und weicht dann auf Imagick aus. Wenn keine der Erweiterungen verfügbar ist oder die Konvertierung fehlschlägt, wird das ursprüngliche Bildformat verwendet und eine Warnung in das Protokoll geschrieben.

Systemvoraussetzungen

Die API-Verbindung funktioniert und Bilder sind im AutoScout24-Inserat vorhanden. Überprüfen Sie dies auf der Systemstatus-Seite.
Das WordPress-Uploads-Verzeichnis ist für den Webserver-Prozess beschreibbar.
Die Option Bilder importieren ist in den Plugin-Einstellungen aktiviert.
Das PHP-Memory-Limit und die maximale Ausführungszeit reichen für das Herunterladen und Verarbeiten von Bildern aus.

Diagnoseschritte

Schritt 1: Bestätigen, dass der Bildimport aktiviert ist

Gehen Sie zum Plugin-Tab Einstellungen (oder Import & Limits, je nach Layout).
Bestätigen Sie, dass Bilder importieren aktiviert ist.
Beachten Sie den Wert für Max. Bilder pro Fahrzeug. Wenn dieser auf eine niedrige Zahl eingestellt ist (z. B. 1), werden nur so viele Bilder pro Fahrzeug heruntergeladen. Stellen Sie ihn auf 0 für unbegrenzt.

Schritt 2: Protokolldatei lesen

Öffnen Sie die Plugin-Protokolldatei unter:

wp-content/uploads/as24ci-logs/adp-car-market-hub.log

Suchen Sie nach folgenden Mustern:

Protokoll-Muster	Bedeutung
`Image download failed for listing_id=… url=… error=…`	`download_url()` hat einen Fehler zurückgegeben. Die Fehlermeldung enthält die Ursache (z. B. HTTP-Timeout, Verbindung verweigert, 404).
`media_handle_sideload failed for listing_id=… url=… error=…`	WordPress konnte die heruntergeladene Datei nicht als Medienanhang registrieren. Häufig ein Problem mit Dateisystemberechtigungen oder Speicherplatz.
`WebP conversion skipped: neither GD imagewebp nor Imagick available.`	Die WebP-Konvertierung ist aktiviert, aber die erforderliche PHP-Erweiterung ist nicht vorhanden.
`WebP GD conversion failed for …, trying Imagick.`	GD ist fehlgeschlagen; Imagick wird als Fallback versucht.
`WebP Imagick conversion failed: …`	Beide Konvertierungsmethoden sind fehlgeschlagen. Das Original-Bildformat wurde gespeichert.
`WebP conversion failed for …, using original.`	Letzter Fallback: Originalbild gespeichert.
`Image queue worker: processed=… errors=… remaining=…`	Zusammenfassung des letzten Durchlaufs des Image-Queue-Workers.
`Image queue worker error post_id=… url=… error=…`	Ein einzelnes Bild ist innerhalb des Queue-Workers fehlgeschlagen.

Schritt 3: Uploads-Verzeichnis überprüfen

Das WordPress-Uploads-Verzeichnis muss für den Webserver beschreibbar sein. Typischer Pfad:

wp-content/uploads/

Überprüfen Sie via FTP, SFTP oder den Datei-Manager des Hostings, ob:

Das Verzeichnis existiert.
Der Webserver-Prozess Schreibrechte besitzt (typischerweise 755 für Verzeichnisse, mit dem Webserver-Benutzer als Eigentümer).
Ausreichend Speicherplatz vorhanden ist.

Wenn das Uploads-Verzeichnis nicht beschreibbar ist, schlägt media_handle_sideload mit einem Dateisystemfehler fehl.

Schritt 4: PHP-Speicher- und Ausführungslimits prüfen

Das Herunterladen und Verarbeiten mehrerer Bilder in einem einzigen Request erfordert ausreichend PHP-Speicher. Wenn das PHP-Memory-Limit zu niedrig ist, kann die Bildverarbeitung geräuschlos fehlschlagen oder einen fatalen Fehler erzeugen.

Überprüfen Sie unter Werkzeuge → Website-Zustand → Info → Server das aktuelle PHP-Memory-Limit und die maximale Ausführungszeit.
Wenn das Memory-Limit bei Websites mit großen Bilddateien unter 256 MB liegt, sollten Sie eine Erhöhung über die wp-config.php (define('WP_MEMORY_LIMIT', '256M')) oder das Hosting-Control-Panel in Betracht ziehen.
Für Cron-Läufe versucht das Plugin, ein Ausführungszeitlimit von 300 Sekunden festzulegen. Wenn die Hosting-Umgebung set_time_limit einschränkt, wird dies möglicherweise nicht wirksam. Verwenden Sie den Bild-Warteschlangen-Modus (standardmäßig aktiviert), um Bild-Downloads auf mehrere kürzere Läufe zu verteilen.

Schritt 5: Erreichbarkeit der Bild-URLs testen

Wenn das Protokoll Image download failed mit einem Netzwerk- oder HTTP-Fehler anzeigt, überprüfen Sie, ob die von der API zurückgegebenen Bild-URLs von Ihrem Server aus öffentlich zugänglich sind:

Kopieren Sie eine Bild-URL aus dem Protokolleintrag.
Versuchen Sie, in einem Browser darauf zuzugreifen. Wenn ein 404- oder Authentifizierungsfehler zurückgegeben wird, wurde das Bild möglicherweise aus der API entfernt oder erfordert eine Authentifizierung, die das Plugin nicht bereitstellt.
Wenn die URL im Browser, aber nicht vom Server aus erreichbar ist, liegt möglicherweise eine IP-Whitelist-, Firewall- oder Proxy-Einschränkung für ausgehende HTTP-Anfragen Ihres Servers vor.

Schritt 6: Status der Bild-Warteschlange überprüfen

Gehen Sie im Plugin zum Tab System & Hilfe.
Suchen Sie nach dem Bereich für die Bild-Warteschlange, der Folgendes anzeigt: verbleibende Elemente, letzte Laufzeit, Anzahl der verarbeiteten und fehlgeschlagenen Elemente.
Wenn Elemente verbleiben und der Queue-Worker kürzlich nicht gelaufen ist, stellen Sie sicher, dass WP-Cron aktiv und der Hook as24ci_image_queue_process geplant ist. Siehe Cron-Jobs und Hintergrundverarbeitung für Details.
Wenn die Bild-Warteschlangensperre (as24ci_image_queue_running) veraltet ist, löschen Sie sie via WP-CLI oder ein Transient-Management-Plugin:

   wp transient delete as24ci_image_queue_running

Schritt 7: Voraussetzungen für die WebP-Konvertierung prüfen

Wenn die WebP-Konvertierung aktiviert ist, Bilder aber als JPEG oder PNG gespeichert werden:

Gehen Sie zu Werkzeuge → Website-Zustand → Info → Server und suchen Sie nach der GD-Bibliothek und Imagick.
GD erfordert die Funktion imagewebp, die in GD mit WebP-Unterstützung (PHP 5.5+) verfügbar ist. Bestätigen Sie dies mit Ihrem Hosting-Anbieter.
Imagick erfordert die PHP-Erweiterung imagick mit einkompilierter WebP-Unterstützung. Bestätigen Sie dies mit Ihrem Hosting-Anbieter.
Wenn keines von beiden verfügbar ist, deaktivieren Sie die WebP-Konvertierung in den Plugin-Einstellungen oder kontaktieren Sie Ihren Hosting-Anbieter, um die erforderliche Erweiterung zu aktivieren.

Konfigurationsreferenz

Einstellung	Auswirkung
Bilder importieren	Hauptschalter. Wenn deaktiviert, werden beim Import keine Bilder heruntergeladen. Standard: aktiviert.
Max. Bilder pro Fahrzeug	Maximale Anzahl der pro Fahrzeug heruntergeladenen Bilder. `0` = unbegrenzt.
Bild-Warteschlangen-Modus	Wenn aktiviert, wird nur das erste Bild sofort heruntergeladen; verbleibende Bilder werden in die Warteschlange gestellt. Standard: aktiviert für Cron-/REST-Läufe.
In WebP konvertieren	Wenn aktiviert, werden heruntergeladene Bilder in das `.webp`-Format konvertiert. Erfordert GD mit WebP-Unterstützung oder Imagick. Standard: deaktiviert.
WebP-Qualität	Kompressionsqualität für die WebP-Konvertierung (1–100). Standard: 80.

Betriebshinweise

Bilder werden mit einem Timeout von 30 Sekunden pro URL heruntergeladen. Langsame oder unzuverlässige externe Bildserver können dazu führen, dass einzelne Bilder fehlschlagen, ohne den Rest des Imports zu beeinträchtigen.
Jedes heruntergeladene Bild wird in der WordPress-Mediathek als Anhang registriert, wobei post_parent auf die Fahrzeug-Beitrags-ID festgelegt ist.
Der Anhangs-Metawert _as24ci_source_url wird für die Deduplizierung verwendet. Wenn diese Meta gelöscht oder beschädigt wird, lädt das Plugin dasselbe Bild beim nächsten Import möglicherweise erneut herunter.
Die Bild-Warteschlange kann bis zu 20.000 Elemente aufnehmen. Wenn dieses Limit überschritten wird, wird eine Warnung protokolliert und ein Deduplizierungsdurchlauf gestartet. Siehe Cron-Jobs und Hintergrundverarbeitung.
Wenn alle Warteschlangenelemente für ein Fahrzeug verarbeitet wurden, wird die Meta _as24ci_image_ids aus den tatsächlichen untergeordneten Anhängen neu erstellt und der Bilder-Hash finalisiert. Bis dahin ist der Hash-Wert auf pending_queue gesetzt, um zu signalisieren, dass das Bilderset noch nicht vollständig ist.
Das dauerhafte Löschen eines Fahrzeug-Beitrags (über die Löschfunktion des Plugins oder aus der WordPress-Fahrzeugliste) löscht auch dauerhaft alle angehängten Bilder, die vom Plugin importiert wurden.

Fehlerbehebung

Symptom	Wahrscheinliche Ursache	Prüfung
Keine Bilder bei allen Fahrzeugen	Bilder importieren ist deaktiviert	In den Plugin-Einstellungen aktivieren
Nur ein Bild pro Fahrzeug	Max. Bilder ist auf `1` eingestellt oder die Bild-Warteschlange ist nicht gelaufen	Einstellung für maximale Bilder prüfen; sicherstellen, dass der Queue-Worker läuft
`Image download failed … HTTP 404`	Bild-URL nicht mehr gültig	Überprüfen, ob das Inserat in AutoScout24 noch Bilder hat; erneut importieren
`Image download failed … connect timed out`	Server kann den externen Bild-Host nicht erreichen	Ausgehenden Netzwerkzugriff prüfen; vom Server aus mit `curl` testen
`media_handle_sideload failed … Could not write file`	Uploads-Verzeichnis nicht beschreibbar oder Festplatte voll	Verzeichnisberechtigungen und verfügbaren Speicherplatz prüfen
WebP-Konvertierung geräuschlos übersprungen	GD/Imagick nicht verfügbar oder nicht mit WebP-Unterstützung kompiliert	Website-Zustand → Server prüfen; WebP-Konvertierung deaktivieren, wenn nicht unterstützt
Bilder in Mediathek vorhanden, aber nicht auf der Fahrzeugseite	Meta `_as24ci_image_ids` fehlt oder ist fehlerhaft	Fahrzeug erneut importieren; Post-Meta in der Datenbank prüfen
Beitragsbild fehlt	Erstes Bild in der Warteschlange wurde möglicherweise noch nicht verarbeitet	Status der Bild-Warteschlange prüfen; sicherstellen, dass der Queue-Worker läuft
Doppelte Bilder in der Mediathek	Meta `_as24ci_source_url` fehlt bei Anhängen	Diese Meta nicht löschen; Support kontaktieren, falls betroffen