Un site Drupal qui affiche une page blanche, une erreur 500 du serveur ou le message « The website encountered an unexpected error. Try again later. » a en général une cause écrite quelque part. Le message affiché au visiteur est volontairement vague ; le vrai message d'erreur est dans un log. Le diagnostic consiste à le trouver vite, sans aggraver la situation. Voici l'ordre que je suis, du moins invasif au plus lourd.

Avant toute manipulation, faites une sauvegarde de la base, même si le site est cassé :

drush sql:dump --gzip --result-file=/var/backups/avant-diagnostic.sql

La commande produit un fichier avant-diagnostic.sql.gz. Si Drush ne démarre plus, mysqldump fait le même travail. Cette sauvegarde vous permet de revenir à l'état de départ si une correction tentée empire les choses.

Étape 1 : noter ce qui a changé

La question la plus utile est « qu'est-ce qui a bougé juste avant ? ». Une mise à jour de module, un déploiement, un changement de version de PHP chez l'hébergeur, un disque plein, un certificat renouvelé. Regardez le dernier commit déployé, la date de modification de composer.lock, l'historique de l'hébergeur. Quand un changement précède de peu la panne, c'est le premier suspect, et il oriente vers le bon log.

Précisez aussi l'étendue du problème : tout le site, seulement l'administration, une seule page, un seul rôle ? Une erreur limitée à /admin ou à un type de contenu pointe vers un module précis ; un site entièrement blanc, vers PHP, la base ou le cache.

Étape 2 : lire les logs de Drupal avec Drush

Si Drupal arrive à démarrer suffisamment pour écrire dans son journal (module Database Logging, dblog), l'erreur y est. La commande drush watchdog:show (alias ws) l'affiche sans passer par l'interface :

drush ws --count=20
drush ws --type=php --extended
drush ws --severity=Error

L'option --extended donne le message complet, avec le fichier et la ligne. Cherchez la première erreur dans le temps, pas la dernière : une exception en déclenche souvent d'autres en cascade.

Si le site utilise syslog à la place de dblog, les messages sont dans le journal système (journalctl ou /var/log/syslog sur Debian, selon la configuration).

Étape 3 : lire les logs du serveur

Quand Drupal ne démarre pas du tout, il n'écrit rien dans son journal. Il faut alors lire les logs du serveur web et de PHP. Sur un serveur Debian avec nginx et PHP-FPM, les emplacements par défaut sont :

tail -n 50 /var/log/nginx/error.log
tail -n 50 /var/log/php8.3-fpm.log

Les erreurs PHP d'un site servi par FPM apparaissent souvent dans le log d'erreur nginx sous la forme FastCGI sent in stderr: "PHP message: PHP Fatal error: ...". Sous Apache, regardez /var/log/apache2/error.log ou le log propre au virtualhost. Sur un hébergement mutualisé, ces logs sont en général accessibles depuis le panneau de l'hébergeur.

Trois familles de messages sont fréquentes :

  • Allowed memory size of ... bytes exhausted : limite mémoire PHP atteinte (étape 6) ;
  • Class "..." not found ou Call to undefined method : code et dépendances désynchronisés, typiquement un composer install non exécuté après un déploiement, ou une classe changée dans une mise à jour ;
  • SQLSTATE[...] : problème de base de données (connexion, table manquante, mise à jour de schéma non passée).

Étape 4 : afficher l'erreur, en sécurité

Si aucun log n'est exploitable, on peut demander à Drupal d'afficher l'erreur. Cela ne se fait jamais sur une production accessible au public, car le message complet expose des chemins, des requêtes et parfois des identifiants. Faites-le sur une copie, ou en dernier recours pendant quelques minutes, en restreignant l'accès.

La méthode propre passe par settings.local.php. Copiez sites/example.settings.local.php vers sites/default/settings.local.php, puis décommentez à la fin de settings.php :

if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
  include $app_root . '/' . $site_path . '/settings.local.php';
}

Dans settings.local.php, le niveau d'affichage des erreurs se règle ainsi :

$config['system.logging']['error_level'] = 'verbose';

// Pour les erreurs qui surviennent avant le démarrage de Drupal :
error_reporting(E_ALL);
ini_set('display_errors', TRUE);
ini_set('display_startup_errors', TRUE);

Les valeurs possibles de error_level sont hide, some, all et verbose (avec la trace d'appel). Une fois la cause identifiée, supprimez ces lignes ou revenez à hide en production. Le fichier d'exemple active aussi d'autres réglages de développement (cache désactivé, services de debug) : ne le laissez pas actif sur un site en ligne.

Étape 5 : reconstruire les caches

Un conteneur de services ou un registre de classes en cache qui ne correspond plus au code provoque des erreurs fatales difficiles à lire, typiquement après une mise à jour de module ou un déploiement partiel. La première chose à tenter :

drush cr

Si Drush échoue lui-même, il existe deux alternatives. Le script core/rebuild.php reconstruit les caches depuis le navigateur, après avoir ajouté temporairement dans settings.php :

$settings['rebuild_access'] = TRUE;

Visitez https://votre-site/core/rebuild.php, puis retirez aussitôt cette ligne. Autre possibilité quand le cache est stocké en base (cas par défaut), vider directement les tables de cache, dont cache_container qui contient le conteneur compilé :

drush sql:query "TRUNCATE cache_container"
# ou, sans Drush, avec le client mysql :
mysql nom_base -e "TRUNCATE cache_container; TRUNCATE cache_bootstrap; TRUNCATE cache_discovery;"

Si le site utilise Redis ou Memcache pour ses caches, c'est ce service qu'il faut vider, et vérifier qu'il tourne : un Redis arrêté suffit à rendre un site blanc.

Étape 6 : vérifier la mise à jour de base, la mémoire et les fichiers

Une mise à jour de base ratée

Après une mise à jour du code, les mises à jour de base de données doivent être exécutées. Listez celles en attente :

drush updatedb:status
drush updb -y

Si drush updb échoue au milieu, ne relancez pas en boucle. Lisez l'erreur : il s'agit souvent de la mise à jour d'un module contrib qui bute sur des données inattendues. On peut vérifier le numéro de schéma enregistré pour un module :

drush php:eval "echo \Drupal::service('update.update_hook_registry')->getInstalledVersion('mon_module');"

Une mise à jour partiellement appliquée peut laisser la base dans un état que ni l'ancien ni le nouveau code ne comprennent. Dans ce cas, le retour à la sauvegarde prise juste avant la mise à jour (étape 7) est en général plus sûr qu'une correction à la main.

La mémoire PHP

La documentation Drupal indique 64 Mo comme minimum et 128 à 256 Mo comme valeurs courantes en production. Un site avec beaucoup de modules, ou une opération lourde (reconstruction de cache, import), peut dépasser la limite. Elle se règle dans la configuration de PHP-FPM ou du virtualhost :

memory_limit = 256M

Augmenter la limite résout le symptôme ; si le site en réclame toujours plus, cherchez la page ou le traitement responsable plutôt que de monter indéfiniment.

Les permissions de fichiers

Le serveur web doit pouvoir écrire dans sites/default/files (et le répertoire privé s'il existe), mais pas dans le code. Après une restauration ou une copie faite avec un autre utilisateur, les dossiers de fichiers deviennent parfois non inscriptibles : les agrégats CSS et JS ne se génèrent plus, et le site peut s'afficher sans mise en forme ou tomber en erreur. Vérifiez propriétaire et droits :

ls -ld web/sites/default/files
sudo -u www-data touch web/sites/default/files/test && rm web/sites/default/files/test

Vérifiez aussi l'espace disque avec df -h : un disque plein empêche l'écriture des fichiers de cache et des sessions, avec des symptômes identiques.

Étape 7 : revenir en arrière proprement

Si la cause est identifiée mais que la correction demande du temps, le plus raisonnable est de remettre le site dans son dernier état fonctionnel, puis de corriger au calme sur une copie. Un retour arrière cohérent implique le code et la base ensemble :

git checkout v2026.10.15        # dernier tag déployé fonctionnel
composer install --no-dev --no-interaction
gunzip -c /var/backups/avant-maj.sql.gz | drush sql:cli   # sauvegarde prise avant la mise à jour
drush cr

Restaurer le code sans la base (ou l'inverse) après une mise à jour de schéma produit exactement le type d'erreur que l'on cherche à éliminer. Si aucune sauvegarde antérieure n'existe, c'est le point à régler en priorité une fois le site rétabli.

Après l'incident

Un écran blanc révèle parfois un problème de fond : un déploiement sans procédure, un hébergeur qui change la version de PHP sans prévenir (voir l'article sur la fin de support de PHP 8.2), des modules en retard de plusieurs versions. Si le site est en panne maintenant, l'intervention urgente est prévue pour ce cas. Une fois le site rétabli, un audit flash permet d'identifier ce qui l'a rendu fragile, et une TMA d'éviter que l'incident se reproduise.