Erreur fatale WooCommerce : guide de dépannage pratique

Symptômes

• Il y a eu une erreur critique sur ce site sur la boutique, les fiches produit, le checkout ou l’administration.
• Un écran blanc ou une réponse HTTP 500.
• Un checkout qui tourne sans fin parce que sa requête échoue avec une 500.
• Un e-mail à l’administrateur du site intitulé Votre site rencontre un problème technique.

Causes les plus fréquentes

Diagnostic

1. Récupérez l’erreur complète

Par ordre de commodité :

1. L’e-mail que WordPress envoie à l’administrateur quand il intercepte une erreur fatale.
2. WooCommerce → État → Journaux, source fatal-errors.
3. Le journal d’erreurs PHP dans le panneau de l’hébergeur.
4. wp-content/debug.log, après avoir activé la journalisation :

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );      // ou un chemin hors de la racine web
define( 'WP_DEBUG_DISPLAY', false ); // n’affichez jamais les erreurs aux clients
@ini_set( 'display_errors', '0' );

2. Lisez-la en quatre parties

PHP Fatal error:  Uncaught TypeError: Unsupported operand types: string + float
  in /var/www/wp-content/plugins/custom-fees/custom-fees.php:142
Stack trace:
#0 /var/www/wp-includes/class-wp-hook.php(324): add_custom_fee(Object(WC_Cart))
#1 /var/www/wp-includes/plugin.php(205): WP_Hook->apply_filters(...)
#2 /var/www/wp-content/plugins/woocommerce/includes/class-wc-cart.php(...): do_action('woocommerce_cart_calculate_fees', ...)

• Type et message : un TypeError, donc des types incorrects, pas un fichier manquant.
• Fichier et ligne : custom-fees.php:142, une extension sur mesure, pas WooCommerce.
• Trace : WooCommerce y est arrivé en calculant les frais du panier.
• Horodatage (dans le préfixe de la ligne du journal) : rapprochez-le de la dernière mise à jour, du dernier déploiement ou du changement de PHP.

3. Rattachez-la à un changement

Regardez ce qui a changé juste avant la première occurrence : mises à jour d’extensions et du thème, nouveau snippet, changement de version de PHP, mise à jour de WooCommerce qui a modifié ce qu’un hook transmet. La plupart des erreurs fatales sont la première exécution d’un nouveau chemin de code après un changement.

Journaux et vérifications techniques

• Journal fatal-errors, journal d’erreurs PHP, debug.log.
• WooCommerce → État → État du système : version de PHP, limite de mémoire, versions de WooCommerce et des extensions.
• Le changelog de l’extension pour la version installée juste avant l’apparition de l’erreur.
• Pour les erreurs de mémoire : quelle requête, à quelle fréquence, et ce qu’elle chargeait.

Solutions

• Revenez à la version précédente du composant qui a introduit l’erreur, comme solution provisoire, le temps de préparer la vraie correction.
• Corrigez le code de façon défensive : vérifiez les valeurs de retour, convertissez les types et gérez les commandes ou produits introuvables.
• Mettez à jour les extensions incompatibles avec les versions actuelles de PHP et de WooCommerce, ou remplacez celles qui sont abandonnées.
• Supprimez les doublons : le même snippet dans une extension de snippets et dans functions.php, ou deux extensions qui embarquent des bibliothèques en conflit.
• Pour les limites de temps et de mémoire, corrigez ce qui est lent ou lourd ; n’augmentez les limites que pour des tâches lourdes légitimes, idéalement en arrière-plan.

// Avant : erreur fatale quand get_option() renvoie une chaîne
$fee = $cart->get_subtotal() * get_option( 'handling_rate' );

// Après : types explicites, et rien à ajouter si le taux n’est pas défini
$rate = (float) get_option( 'handling_rate', 0 );
if ( $rate > 0 ) {
    $cart->add_fee( __( 'Frais de gestion', 'my-store' ), $cart->get_subtotal() * $rate );
}

Ce qu’il ne faut pas faire

• N’activez pas l’affichage des erreurs sur une boutique en production ; journalisez-les.
• Ne modifiez pas les fichiers d’une extension tierce en production. La modification disparaît à la prochaine mise à jour et personne ne sait qu’elle existe.
• Ne réinstallez pas WooCommerce et ne restaurez pas une ancienne sauvegarde sans connaître la cause : vous risquez de perdre des commandes et de garder le bug.
• Ne supprimez pas le journal après l’avoir lu ; vous en aurez besoin pour confirmer la correction.

Quand faire appel à un expert

Faites appel à un ingénieur quand l’erreur se trouve dans du code sur mesure ou une extension premium que vous ne pouvez pas modifier sans risque, quand elle est intermittente, quand elle est apparue dans de nombreux fichiers après une mise à jour de PHP, ou quand elle bloque le checkout ou l’administration en ce moment.

Problèmes liés

• WooCommerce / Erreurs Conflit d’extensions WooCommerce : comment trouver la cause Partez des preuves (l’erreur, le moment, la requête) et isolez en préproduction par moitiés, pas extension par extension en production. →
• WooCommerce / Checkout Le checkout WooCommerce ne fonctionne pas : trouver la cause racine Déterminez d’abord si l’échec se produit avant la requête de commande, pendant celle-ci ou après la réponse de la passerelle. Le panneau Réseau et les journaux PHP montrent généralement quelle couche casse. →
• WooCommerce / HPOS HPOS WooCommerce : problèmes fréquents avec le code personnalisé Requêtes directes sur wp_posts, get_post_meta() sur les commandes et autre code qui casse en silence quand les commandes passent dans leurs propres tables. →

Questions fréquentes