---
title: "Dépannage"
description: "Dépannage Éclair par symptôme : installation, erreurs 404 et 500, mot de passe oublié, images, e-mails, assistant IA, MCP et polices."
url: "https://eclair.academy/documentation/depannage"
lang: "fr"
author: "Thierry Gustin"
published: "2026-11-02"
updated: "2026-11-02"
---

# Dépannage

> **L’essentiel** — Pour le dépannage d'Éclair, pars du symptôme. La plupart des problèmes viennent d'un .htaccess non envoyé (404), d'une version de PHP trop ancienne, d'un dossier non accessible en écriture ou de connexions sortantes bloquées par l'hébergeur. Un mot de passe oublié se règle avec data/reset.php, une installation verrouillée en supprimant data/install-window.php.

Cette page de dépannage Éclair part de ce que tu vois : un message, une erreur 404, un e-mail qui n'arrive pas. Commence par le tableau de diagnostic rapide, puis ouvre la section du symptôme. Chaque solution s'appuie sur le guide officiel et sur le code d'Éclair 1.8.0 ; les messages sont cités tels qu'ils s'affichent.

## Diagnostic rapide : le dépannage Éclair en un tableau

| Symptôme | Cause probable | Solution |
| --- | --- | --- |
| Toutes les pages sauf l'accueil répondent 404 | `.htaccess` non envoyé, ou réécriture désactivée | Envoie le `.htaccess` (fichier caché) ; décommente `RewriteBase /` si l'hébergeur l'exige |
| Erreur 500 juste après l'envoi | Une directive du `.htaccess` est refusée | Supprime le bloc concerné ou contacte ton hébergeur |
| « Éclair a besoin de PHP 8.1 ou plus récent » | Version de PHP trop ancienne | Change la version de PHP dans ton espace client |
| « Installation verrouillée » | Fenêtre de 2 heures dépassée | Supprime `data/install-window.php` et recharge |
| Mot de passe oublié ou téléphone de 2FA perdu | Aucun autre administrateur pour t'aider | Fichier `data/reset.php` |
| « Trop de tentatives… » | Limite anti-bruteforce atteinte | Attends 15 minutes, ou fais débloquer l'adresse |
| Adresse du site non vérifiée (page Sécurité) | Le serveur n'arrive pas à se joindre lui-même | **Vérifier l'adresse du site** une fois le domaine en place |
| Images non converties en WebP | Extension GD absente | Active GD dans le panneau PHP |
| E-mails du formulaire absents | Expéditeur refusé, message classé en spam | Vérifie **Messages** et Réglages › Contact |
| « Impossible de joindre… » dans l'assistant | Connexions sortantes bloquées | Fais autoriser l'API par ton hébergeur |
| Claude ou ChatGPT ne se connecte pas | Pas de HTTPS, sous-dossier, pare-feu | HTTPS, installation à la racine, laisser passer `/_eclair/` et `/.well-known/` |
| Police de titre remplacée par une police de secours | Téléchargement de la police bloqué | Réessaie plus tard en enregistrant de nouveau |
| « Oups, un court-circuit. » | Erreur PHP inattendue | Note la **Référence** et consulte la page **Sécurité** |

## Problèmes d'installation

Ces cas de dépannage Éclair surviennent pendant les premières minutes, avant même la première connexion à l'administration.

### « Éclair a besoin de PHP 8.1 ou plus récent »

La page affiche aussi ta version actuelle. Change la version de PHP dans l'espace client de ton hébergeur (souvent en un clic), puis recharge la page. Vise PHP 8.3 : l'assistant d'installation conseille d'y passer en dessous de 8.2, et la page Sécurité ne valide « Version de PHP maintenue » qu'à partir de 8.2. Le calendrier de support des versions est publié sur [php.net](https://www.php.net/supported-versions.php).

### Un point est en rouge ou en orange dans l'assistant

| Point vérifié | Que faire |
| --- | --- |
| Extension mbstring, json, dom, session ou zlib | Indispensable : active-la dans le panneau PHP de ton hébergeur. |
| Dossier « data », « cache » ou « media » accessible en écriture | Donne les droits d'écriture (755) à ce dossier via ton FTP. |
| Adresses propres (réécriture d'URL) inactives | Vérifie que le fichier `.htaccess` a bien été envoyé (fichier caché). |
| Connexion sécurisée (HTTPS) | Active le certificat SSL gratuit (Let's Encrypt) de ton hébergeur, puis recharge en `https://`. |
| Traitement des images (GD) | Sans GD, les images ne sont ni redimensionnées ni converties. |
| Sauvegardes en un clic (ZIP) | Sans l'extension zip, la sauvegarde se fera par FTP. |
| Assistant IA (cURL et chiffrement) | Sans curl, sodium ou openssl, l'assistant IA ne pourra pas être activé. |

Si le message « Active JavaScript pour installer Éclair. » s'affiche, autorise JavaScript dans ton navigateur. Depuis la 1.8.0, zlib est indispensable : les écrans de l'administration sont livrés compressés.

### « Installation verrouillée »

Par sécurité, l'installation doit être faite dans les 2 heures qui suivent la première visite : sinon, n'importe qui pourrait prendre le contrôle d'un site déposé puis oublié. Pour rouvrir la fenêtre, supprime le fichier `data/install-window.php` avec ton logiciel FTP ou le gestionnaire de fichiers de ton hébergeur, puis recharge la page.

## Erreurs 404, 500 et pages d'erreur

### Erreur 404 sur toutes les pages sauf l'accueil

Le fichier `.htaccess` n'a pas été envoyé (c'est un fichier caché) ou la réécriture d'adresses est désactivée. Active l'affichage des fichiers cachés dans ton logiciel FTP, renvoie le `.htaccess` à la racine d'Éclair, puis recharge. Si ton hébergeur l'exige, décommente la ligne `RewriteBase /`. Sous Nginx, le `.htaccess` est ignoré : reproduis les règles décrites dans [Fichiers, dossiers et adresses](https://eclair.academy/documentation/fichiers).

### Erreur 500 juste après l'envoi

Une directive du `.htaccess` est refusée par ton hébergeur. C'est très rare : Éclair n'utilise que des directives tolérées sur les mutualisés. Supprime le bloc concerné, ou demande à ton hébergeur laquelle pose problème.

### « Oups, un court-circuit. »

Cette page signale une erreur inattendue et affiche une **Référence**. Connecte-toi à l'administration : la page **Sécurité** liste les **Dernières erreurs techniques** avec cette référence, le message et l'emplacement. Le bouton **Reconstruire l'index et vider le cache**, affiché dans cette section, reconstruit l'index des contenus (`data/index.php`) et vide le cache.

### Afficher le détail des erreurs

C'est l'outil de base de tout dépannage Éclair un peu tenace. Crée un fichier `eclair-config.php` à la racine, à partir de `eclair-config.exemple.php`, avec la ligne `define('ECLAIR_DEBUG', true);`. Les erreurs s'affichent alors en détail. Ce mode coupe aussi le cache statique : supprime la ligne dès que le problème est réglé.

## Connexion et comptes

### Mot de passe oublié ou 2FA perdue : que faire ?

Si un autre administrateur existe, il ouvre ton compte dans **Utilisateurs** et clique sur **Réinitialiser le mot de passe** (un mot de passe provisoire est généré) ou sur **Désactiver la 2FA**. Avec la 2FA active, un de tes 8 codes de secours remplace aussi le code du téléphone.

Si tu es le seul administrateur, crée par FTP un fichier `data/reset.php` contenant exactement ces trois lignes :

```text
<?php exit; ?>
ton-adresse@email.fr
TonNouveauMotDePasse2026
```

1. Remplace la deuxième ligne par l'e-mail de ton compte, la troisième par ton nouveau mot de passe.
2. Dans les 24 heures, connecte-toi avec cet e-mail et ce nouveau mot de passe.
3. Le mot de passe est remplacé, la double authentification du compte est désactivée, tes autres sessions sont fermées et le fichier est supprimé automatiquement.

Personne d'autre ne peut déclencher ce secours : il faut connaître le contenu du fichier. Un fichier sans la première ligne, ou créé il y a plus de 24 heures, est refusé et supprimé. Le nouveau mot de passe doit respecter les règles habituelles (10 caractères au moins, pas un mot de passe courant) ; sinon, le journal de sécurité indique « Réinitialisation par FTP refusée ».

### « Trop de tentatives. Par sécurité, réessaie dans quelques minutes. »

Après 10 essais ratés en 15 minutes depuis un même réseau, la connexion est bloquée 15 minutes ; après 30 essais ratés en une heure sur un même compte, ce compte est bloqué une heure pour les appareils inconnus. Ton appareil habituel a son propre compteur : un attaquant qui se trompe exprès ne le bloque pas. Un autre administrateur peut lever un blocage dans **Sécurité** › **Sessions et blocages** › **Débloquer**.

### Le code de double authentification est refusé

Le message « Code incorrect. Vérifie l'heure de ton téléphone ou utilise un code de secours. » vient presque toujours d'une horloge décalée : le code change toutes les 30 secondes. Règle l'heure du téléphone sur automatique. Après 10 codes faux, la double authentification du compte est bloquée 15 minutes et son titulaire est prévenu par e-mail.

### « Jeton de sécurité expiré » ou « Session expirée »

La page est restée ouverte trop longtemps, ou la session a pris fin après la durée d'inactivité (240 minutes par défaut, réglable dans **Réglages › Avancé**). Recharge la page ou reconnecte-toi dans un autre onglet. Dans l'éditeur, rien n'est perdu : un brouillon local de secours propose « Une version non enregistrée a été retrouvée. La restaurer ? » à la réouverture.

### « Choisis d'abord ton mot de passe personnel »

Un compte créé ou réinitialisé par un administrateur reçoit un mot de passe provisoire. Tant qu'il n'est pas remplacé dans **Mon profil**, le reste de l'administration reste fermé.

### Adresse de l'administration oubliée

Télécharge le fichier `data/site.php` par FTP et ouvre-le dans un éditeur de texte, sans le modifier. La valeur qui suit `"admin_path"` est ton adresse : `"admin_path": "mon-bureau"` correspond à `https://ton-site.fr/mon-bureau`.

## Adresse, HTTPS et cache

### Adresse du site non vérifiée sur la page Sécurité

Ton serveur n'arrive pas à s'appeler lui-même sur l'adresse du site : pare-feu de l'hébergeur, DNS pas encore propagé… Le site fonctionne normalement, mais sans redirection vers l'adresse officielle (avec ou sans `www`). Une fois le domaine en place, clique sur **Vérifier l'adresse du site**. En cas d'échec, le message « Vérification impossible : ton serveur ne parvient pas à joindre… » s'affiche ; demande à ton hébergeur si les requêtes du serveur vers son propre domaine sont bloquées.

### « Active d'abord HTTPS chez ton hébergeur… »

Ce message apparaît si tu coches **Forcer HTTPS** alors que tu es connecté en `http://`. Active le certificat chez ton hébergeur, reconnecte-toi en `https://`, puis coche l'option : l'adresse officielle passe alors en `https://`.

### Pourquoi mes modifications n'apparaissent-elles pas sur le site ?

1. Vérifie le statut : un **Brouillon** n'est jamais visible ; un contenu **Programmé** paraît à l'heure du site (fuseau de **Réglages › Général**).
2. Un produit publié reste invisible tant que la boutique est fermée.
3. Le cache d'Éclair se vide à chaque modification. Si un CDN ou un proxy est placé devant ton site, vide aussi son cache.
4. En dernier recours : **Réglages › Avancé › Vider le cache**, puis recharge la page.

## Images, e-mails et formulaire

### Pourquoi les images ne sont-elles pas converties en WebP ?

L'extension GD (ou son support WebP) manque. La médiathèque l'indique : « L'extension GD est absente sur ton hébergement : les images sont gardées telles quelles. » Active GD dans le panneau PHP de ton hébergeur. Les déclinaisons WebP sont créées à l'envoi : renvoie ensuite les images importantes, celles d'avant restent en JPG ou PNG.

### Un envoi d'image est refusé

| Message | Solution |
| --- | --- |
| « Format non pris en charge : JPG, PNG, WebP ou GIF uniquement. » | Convertis l'image : le SVG et les autres formats sont refusés. |
| « Image trop lourde (20 Mo maximum). » | Compresse ou réduis le fichier. |
| « Fichier trop lourd pour ton hébergement (max …). » | Ta limite PHP d'envoi est plus basse : réduis l'image, ou relève la limite dans le panneau PHP. |
| « Image trop grande pour la mémoire de ton hébergement : réduis-la sous 4000 pixels de large. » | Redimensionne l'image avant l'envoi. |
| « Dimensions d'image invalides ou trop grandes (40 mégapixels maximum). » | Redimensionne l'image. |
| « Image refusée : elle contient du code. » | Fichier piégé ou abîmé : ne l'utilise pas. |
| « Impossible d'enregistrer l'image : vérifie les droits du dossier media. » | Donne les droits d'écriture au dossier `media/`. |

### Pourquoi les e-mails du formulaire n'arrivent-ils pas ?

- Ouvre **Messages** : les messages y sont conservés si l'option **Conserver aussi les messages dans l'administration** est cochée, ce qui est le cas par défaut.
- Un message marqué **Spam probable** est gardé mais n'est pas envoyé par e-mail. C'est le cas s'il contient plus de 3 liens ou s'il arrive sans le jeton du formulaire.
- Vérifie **Recevoir les messages à l'adresse** dans **Réglages › Contact** ; vide, c'est l'e-mail du premier administrateur.
- Éclair envoie avec la fonction `mail()` de PHP, depuis `no-reply@` suivi du domaine de l'**Adresse officielle du site**. Vérifie cette adresse dans **Réglages › Général**. Certains hébergeurs exigent un expéditeur du domaine, d'autres limitent `mail()` : renseigne-toi auprès du tien.
- Regarde dans tes courriers indésirables.

### Le formulaire affiche « L'envoi a échoué… »

Les champs sont incomplets (le message doit compter au moins 5 caractères), ou une limite anti-spam est atteinte : 5 messages par réseau toutes les 10 minutes, 100 par jour pour tout le site. Au-delà, le formulaire refuse les envois pendant 30 minutes pour ce réseau, ou 6 heures pour le site.

## Assistant IA

| Message ou symptôme | Solution |
| --- | --- |
| « Clé d'API refusée » | Clé copiée incomplète ou révoquée : colle-la de nouveau et clique sur **Tester la connexion**. |
| « Crédit épuisé » | Recharge ton compte chez le fournisseur. |
| « Budget IA du mois atteint » | Augmente **Budget mensuel maximum (dollars)** dans **Réglages › Assistant IA**, ou attends le mois suivant. |
| La réponse arrive d'un bloc | Un tampon de l'hébergeur retient le flux : tout fonctionne, sans l'effet en direct. Sous Nginx, ajoute `fastcgi_buffering off;` dans le bloc PHP. |
| « Impossible de joindre… » | L'hébergeur bloque les connexions sortantes : demande-lui d'autoriser `api.anthropic.com` ou `api.openai.com`, et le générateur d'images choisi. |
| L'assistant ne s'affiche pas | Il faut l'extension cURL et le chiffrement (sodium ou openssl), un fournisseur choisi avec sa clé, et pour un rédacteur l'option **Les rédacteurs peuvent utiliser l'assistant**. |
| Les clés semblent avoir disparu | Tu as ajouté ou changé `ECLAIR_SECRET` après les avoir enregistrées : colle-les de nouveau. |
| « Annuler » n'est plus proposé | Quelqu'un a modifié le contenu depuis : passe par l'**Historique des versions** de l'éditeur. |

Le quota de **Demandes par personne et par jour** (60 par défaut) se règle au même endroit que le budget. La mise en service complète est dans [Activer l'assistant IA intégré](https://eclair.academy/parcours/ia-mcp/assistant-ia).

## Connecteur MCP

- **L'IA ne joint pas le site, ou l'autorisation échoue** : vérifie que le site est en HTTPS et que l'adresse se termine par `/_eclair/mcp`. Sur Apache, garde le `.htaccess` d'Éclair à jour : il transmet l'en-tête d'autorisation que certains hébergements retirent.
- **Éclair est installé dans un sous-dossier** : certaines applications cherchent l'autorisation à la racine du domaine. Installe plutôt Éclair à la racine d'un domaine ou d'un sous-domaine.
- **Pare-feu ou protection anti-robots** (Cloudflare…) : laisse passer `/_eclair/` et `/.well-known/`.
- **Les adresses du connecteur répondent 404** : c'est normal tant que **Autoriser les connexions MCP** n'est pas coché.
- **Une proposition ne s'applique plus** : le contenu a changé depuis (« Ce contenu a été modifié depuis la proposition… ») ; redemande la modification à l'IA.
- **L'accès a été coupé** : changer de mot de passe ou déconnecter tous tes appareils coupe les applications connectées, et 60 jours sans usage obligent à redonner ton accord.

Les étapes de connexion sont dans [Connecter Claude à ton site](https://eclair.academy/parcours/ia-mcp/connecter-claude) et [Connecter ChatGPT à ton site](https://eclair.academy/parcours/ia-mcp/connecter-chatgpt).

## Boutique

- **« La boutique reste fermée : publie d'abord ces pages… »** : publie tes mentions légales et tes conditions générales de vente, puis choisis-les dans **Réglages › Boutique** avant de cocher **Boutique ouverte**.
- **« Cette adresse est déjà utilisée : choisis-en une autre. »** : une page occupe déjà l'adresse prévue pour la boutique ; choisis une autre **Adresse de la boutique**.
- **Le bouton « Acheter » reste désactivé** : la fiche n'a pas de lien de paiement. L'analyse le signale ; colle le lien Stripe, PayPal ou Revolut Business dans la fiche produit.
- **Le bouton d'une variante reste désactivé** : une variante à un autre prix n'hérite pas du lien du produit, car le prestataire encaisserait le mauvais montant. Crée-lui son propre lien de paiement, comme le rappelle l'analyse.
- **Les produits n'apparaissent pas sur le site** : ni les fiches ni le bloc Produits ne s'affichent tant que la boutique est fermée.

La mise en route complète est dans [Vendre avec la boutique légère](https://eclair.academy/parcours/intermediaire/boutique).

## Police des directions artistiques

La police de titre d'une direction artistique est téléchargée une seule fois par ton serveur, depuis Fontsource (adresse `cdn.jsdelivr.net`), puis servie par ton site. Si ton hébergeur bloque les connexions sortantes, un message te prévient et le site utilise une police de secours de la même famille (avec empattements, condensée…). Réessaie plus tard en enregistrant de nouveau **Réglages › Apparence**, ou demande à ton hébergeur d'autoriser cette adresse.

## Selon ton hébergeur

Une bonne partie du dépannage Éclair dépend de ce que ton hébergeur autorise. Les cinq points à vérifier :

- **Fichiers cachés** : active leur affichage dans ton logiciel FTP ou dans le gestionnaire de fichiers avant d'envoyer Éclair.
- **Version de PHP** : elle se change le plus souvent en un clic dans l'espace client.
- **Connexions sortantes** : l'assistant IA, la police des directions, IndexNow et la vérification de l'adresse en ont besoin.
- **Envoi d'e-mails** : certains hébergeurs exigent un expéditeur du domaine ou limitent `mail()`.
- **Nginx** : les règles du `.htaccess` sont à reproduire dans la configuration du serveur.

Les particularités de chaque hébergeur sont détaillées dans [Choisir son hébergement](https://eclair.academy/hebergement) et dans [la méthode universelle cPanel, Plesk, DirectAdmin](https://eclair.academy/hebergement/cpanel-plesk-directadmin).

## Questions fréquentes sur le dépannage

### Comment activer le mode débogage d'Éclair ?

Crée `eclair-config.php` à côté d'`index.php` (copie `eclair-config.exemple.php`) avec `define('ECLAIR_DEBUG', true);`. Supprime la ligne une fois le problème réglé : ce mode coupe le cache statique.

### Mon site est-il en panne si la page Sécurité indique une adresse non vérifiée ?

Non. Le site fonctionne normalement, mais Éclair ne redirige personne vers l'adresse officielle tant qu'elle n'est pas vérifiée. Clique sur **Vérifier l'adresse du site** une fois le domaine en place.

### Que faire si aucune solution de cette page de dépannage Éclair ne marche ?

Note ta version d'Éclair et de PHP, ton hébergeur et la référence de l'erreur, puis ouvre une demande dans les [issues GitHub d'Éclair](https://github.com/Jacckisback/eclair-cms/issues). N'y mets jamais de mot de passe ni de clé d'API.