Dépannage d’Artisan

En bref

Chaque défaillance du pont remonte sous forme d’exception typée. Associe l’exception et son message au tableau ci-dessous. Chaque ligne pointe vers le contrôle source exact, ce qui te permet de corriger la cause plutôt que le symptôme.

Diagnostiquer par exception

`ChromeNotAvailableException`

chrome-php/chrome is not installed. Install it via: composer require chrome-php/chrome:^1.15

La bibliothèque cliente CDP est absente de l’autoloader. BrowserPool::getBrowser() lève cette exception avant tout lancement de Chrome. Exécute la commande d’installation. Ce cas est distinct d’un binaire manquant : le contrôle de la bibliothèque et le contrôle du binaire sont deux étapes séparées.

`ChromeRenderException` — lancement ou délai d’expiration

Chrome renderer failed: <cause>

Chrome n’a pas pu démarrer, a dépassé le délai d’expiration ou a planté. L’exception précédente contient la cause d’origine. Causes courantes :

Binaire introuvable ou non exécutable. Vérifie avec chromium --headless --dump-dom about:blank. Définis chrome_binary sur le chemin absolu.
Le bac à sable ne peut pas s’initialiser (conteneurs). La cause mentionne le bac à sable ou l’espace de noms. Provisionne un conteneur compatible avec le bac à sable (recommandé), ou définis no_sandbox: true après avoir consulté /integrations/artisan/security-and-operations/.
Délai d’expiration dépassé. Un document lourd a dépassé render_timeout. Augmente le délai pour cette charge de travail ou réduis le document ; évalue le compromis lié au déni de service sur un chemin exposé aux utilisateurs.
Bibliothèques partagées manquantes. Chrome se ferme immédiatement. Installe l’ensemble des dépendances Chrome de la distribution.

`ChromeRenderException` — sortie vide

Chrome printToPDF returned empty data

Chrome a démarré et printToPDF a renvoyé zéro octet. La cause habituelle est une entrée qui ne produit aucune boîte rendue (corps vide, tout le contenu en display:none) ou un plantage de Chrome pendant l’impression. Confirme que le HTML produit une boîte visible. Contrôle la pression mémoire de l’hôte.

`RuntimeException` — entrée rejetée avant Chrome

Le message contient	Cause	Correction
`exceeds maximum allowed size`	HTML dépassant `maxHtmlSize`	Réduis l’entrée ou augmente `max_html_size` (élargit la surface d’épuisement des ressources)
`oversized base64 data URI`	Base64 incorporé ≥ 13 Mo	Réduis la ressource intégrée ; fais référence à une image plus petite
`forbidden meta refresh redirect`	`<meta http-equiv="refresh">` présent	Supprime la balise ; c’est un vecteur de navigation SSRF et elle est toujours rejetée

Ces erreurs proviennent de ChromeSecurityPolicy::validate() et se déclenchent avant tout contact avec Chrome, ce qui les rend rapides et peu coûteuses à couvrir dans les tests.

`PdfParseException`

Page <n> has no content stream

Chrome a produit un PDF dont le parseur n’a pas pu extraire de page. C’est rare et cela indique une sortie Chrome malformée ou une version de Chrome qui produit une structure inattendue. Capture la version de Chrome et l’entrée. Vérifie que le binaire est une build Chrome/Chromium prise en charge.

Les ressources distantes s’affichent en blanc

Ce n’est pas un bug. Le pont bloque toute récupération de sous-ressource (CSP default-src 'none' plus un blocage CDP setBlockedURLs('*')). Les <img> distants, les feuilles de style, les polices, les scripts et les iframes ne se chargent pas. Intègre les ressources sous forme d’URI data: et le CSS via defaultCss ou <style>. Consulte le modèle réseau sur /integrations/artisan/security-and-operations/.

Contenu tronqué en bas de page

Le document a débordé sur une deuxième page Chrome et le pont n’a importé que la page 0. Soit le tampon d’ajustement automatique était trop petit pour un reflux exceptionnellement haut, soit une hauteur explicite était trop faible. Fournis une hauteur explicite dimensionnée au contenu, ou supprime la hauteur explicite pour utiliser l’ajustement automatique avec son tampon de sécurité. Consulte la gestion de la hauteur sur /integrations/artisan/production-usage/.

Pic de latence tous les ~100 rendus

C’est attendu. BrowserPool redémarre Chrome tous les 100 rendus pour borner la mémoire. Une ligne de journal de niveau notice enregistre le redémarrage avec le nombre de rendus. Traite-le comme un coût périodique connu dans tes SLO, pas comme un incident. Un taux de redémarrage supérieur à un tous les 100 rendus indique des documents plus lourds que prévu.

La mémoire augmente au cours d’un long lot

BrowserPool borne la croissance avec le redémarrage tous les 100 rendus, mais un worker à très longue durée de vie peut tout de même accumuler de la mémoire. Appelle close() entre les gros lots pour recycler le processus Chrome plus tôt, et exécute le worker sous une limite de mémoire de l’hôte.

Liste de contrôle de diagnostic

Reproduis avec un fragment HTML minimal et de confiance pour isoler l’entrée de l’environnement.
Exécute chromium --headless --dump-dom about:blank sur l’hôte, sous l’utilisateur du worker.
Injecte un logger PSR-3 et lis les lignes info/notice (chemin du binaire, nombre de redémarrages).
Confirme que chrome-php/chrome est installé : c’est le cas si BrowserPool::getBrowser() ne lève pas ChromeNotAvailableException.
Vérifie l’exception précédente rattachée à l’exception pour connaître la cause Chrome sous-jacente.

Voir aussi

/integrations/artisan/install/
/integrations/artisan/configuration/
/integrations/artisan/security-and-operations/
/integrations/artisan/chrome-renderer-setup/
/integrations/artisan/production-usage/