Troubleshooting

This Éclair CMS troubleshooting page starts from what you see: a message, a 404 error, an email that never arrives. Begin with the quick diagnosis table, then open the section for your symptom. Each solution is based on the official guide and on the code of Éclair 1.8.0; messages are quoted exactly as they're displayed.

Quick diagnosis: Éclair CMS troubleshooting in one table

Installation problems

These Éclair CMS troubleshooting cases come up in the first few minutes, before you even log in to the admin for the first time.

PHP 8.1 or later required

The page, shown in French only, reads “Éclair a besoin de PHP 8.1 ou plus récent” (“Éclair needs PHP 8.1 or later”) and also gives your current version. Change the PHP version in your host's customer area (often in one click), then reload the page. Aim for PHP 8.3: the setup wizard recommends upgrading to it if you're below 8.2, and the Security page only ticks “Supported PHP version” from 8.2 onward. The support schedule for PHP versions is published on php.net.

A check is red or orange in the setup wizard

If the message “Enable JavaScript to install Éclair.” appears, allow JavaScript in your browser. Since 1.8.0, zlib is required: the admin screens ship compressed.

“Installation locked”

For security, installation must be completed within 2 hours of the first visit: otherwise, anyone could take over a site that was uploaded and then forgotten. To reopen the window, delete the data/install-window.php file with your FTP client or your host's file manager, then reload the page.

404 errors, 500 errors and error pages

404 error on every page except the home page

The .htaccess file wasn't uploaded (it's a hidden file) or URL rewriting is disabled. Turn on the display of hidden files in your FTP client, upload the .htaccess file again to Éclair's root, then reload. If your host requires it, uncomment the RewriteBase / line. On Nginx, .htaccess is ignored: reproduce the rules described in Files, folders and URLs.

500 error right after uploading

Your host refuses a .htaccess directive. This is very rare: Éclair only uses directives tolerated on shared hosting. Remove the block in question, or ask your host which one causes the problem.

The “Oups, un court-circuit.” error page

This page, always shown in French (“Oops, a short circuit.”), reports an unexpected error and displays a reference, labeled Référence. Log in to the admin: the Security page lists the Recent technical errors with this reference, the message and the location. The Rebuild the index and clear the cache button, shown in that section, rebuilds the content index (data/index.php) and clears the cache.

Show error details

This is the basic tool for any stubborn bit of Éclair CMS troubleshooting. Create an eclair-config.php file at the root, based on eclair-config.exemple.php, with the line define('ECLAIR_DEBUG', true);. Errors are then shown in detail. This mode also turns off the static cache: delete the line as soon as the problem is solved.

Login and accounts

Forgotten password or lost 2FA: what should you do?

If there's another administrator, they open your account in Users and click Reset password (a temporary password is generated) or Disable 2FA. With 2FA turned on, one of your 8 backup codes can also stand in for the code from your phone.

If you're the only administrator, create a data/reset.php file via FTP containing exactly these three lines:

<?php exit; ?>
your-address@example.com
YourNewPassword2026

1. Replace the second line with your account's email and the third with your new password.
2. Within 24 hours, log in with that email and that new password.
3. The password is replaced, two-factor authentication for the account is turned off, your other sessions are closed and the file is deleted automatically.

Nobody else can trigger this recovery: they would need to know the file's contents. A file without the first line, or created more than 24 hours earlier, is refused and deleted. The new password must follow the usual rules (at least 10 characters, not a common password); otherwise, the security log shows “FTP reset rejected”.

“Too many attempts. For security, try again in a few minutes.”

After 10 failed attempts in 15 minutes from the same network, login is blocked for 15 minutes; after 30 failed attempts in an hour on the same account, that account is blocked for an hour on unknown devices. Your usual device has its own counter: an attacker who fails on purpose can't lock it. Another administrator can lift a block in Security › Sessions and blocks › Unblock.

The two-factor authentication code is rejected

The message “Wrong code. Check your phone’s time or use a backup code.” almost always comes from a clock that's out of sync: the code changes every 30 seconds. Set your phone's time to automatic. After 10 wrong codes, two-factor authentication for the account is locked for 15 minutes and its owner is notified by email.

“Security token expired” or “Session expired”

The page stayed open too long, or the session ended after the inactivity period (240 minutes by default, adjustable in Settings › Advanced). Reload the page or log in again in another tab. In the editor, nothing is lost: when you reopen the content, a local backup draft offers “An unsaved version was found. Restore it?”.

“First choose your own password”

An account created or reset by an administrator receives a temporary password. Until it's replaced in My profile, the rest of the admin stays closed.

Forgotten admin URL

Download the data/site.php file via FTP and open it in a text editor, without changing it. The value after "admin_path" is your admin URL: "admin_path": "my-office" corresponds to https://example.com/my-office.

URL, HTTPS and cache

Site address not verified on the Security page

Your server can't call itself at the site's address: host firewall, DNS not propagated yet… The site works normally, but without redirects to the official URL (with or without www). Once the domain is in place, click Verify the site address. If that fails, the message “Verification failed: your server can’t reach…” appears; ask your host whether requests from the server to its own domain are blocked.

“Enable HTTPS with your host first…”

This message appears if you check Force HTTPS while you're logged in over http://. Enable the certificate with your host, log in again over https://, then check the option: the official URL then switches to https://.

Why don't my changes show up on the site?

1. Check the status: a Draft is never visible; Scheduled content appears at the site's time (the time zone in Settings › General).
2. A published product stays hidden as long as the shop is closed.
3. Éclair's cache clears itself on every change. If a CDN or a proxy sits in front of your site, clear its cache too.
4. As a last resort: Settings › Advanced › Clear cache, then reload the page.

Images, emails and the contact form

Why aren't images converted to WebP?

The GD extension (or its WebP support) is missing. The media library says so: “The GD extension is missing on your hosting: images are kept as is.” Enable GD in your host's PHP panel. WebP versions are created on upload: upload your important images again afterwards, since the earlier ones stay in JPG or PNG.

An image upload is refused

Why aren't the form emails arriving?

• Open Messages: messages are kept there if the Also keep messages in the admin option is checked, which it is by default.
• A message marked Likely spam is kept but not sent by email. That happens if it contains more than 3 links or arrives without the form's token.
• Check Receive messages at in Settings › Contact; if it's empty, the first administrator's email is used.
• Éclair sends email with PHP's mail() function, from no-reply@ followed by the domain of the Official site URL. Check this URL in Settings › General. Some hosts require a sender from the domain, others limit mail(): check with yours.
• Look in your spam folder.

The visitor sees “Sending failed. Check the fields and try again.”

The fields are incomplete (the message must be at least 5 characters long), or an anti-spam limit has been reached: 5 messages per network every 10 minutes, 100 per day for the whole site. Beyond that, the form refuses submissions for 30 minutes for that network, or 6 hours for the site.

AI assistant

The Requests per person per day quota (60 by default) is set in the same place as the budget. The complete setup is in Turning on the built-in AI assistant.

MCP connector

• The AI can't reach the site, or authorization fails: check that the site uses HTTPS and that the URL ends with /_eclair/mcp. On Apache, keep Éclair's .htaccess up to date: it passes along the authorization header that some hosts strip.
• Éclair is installed in a subfolder: some apps look for authorization at the root of the domain. Install Éclair at the root of a domain or subdomain instead.
• Firewall or bot protection (Cloudflare…): let /_eclair/ and /.well-known/ through.
• The connector URLs return a 404: that's normal as long as Allow MCP connections isn't checked.
• A suggestion no longer applies: the content has changed since (“This content has changed since the proposal…”); ask the AI for the change again.
• Access was cut off: changing your password or logging out all your devices cuts off connected apps, and after 60 days without use you have to give your approval again.

The connection steps are in Connect Claude to your site and Connect ChatGPT to your site.

Shop

• “The shop stays closed: publish these pages first…”: publish your legal notice and your terms of sale, then select them in Settings › Shop before checking Shop open.
• “This URL is already in use: pick another one.”: a page already uses the URL planned for the shop; choose another Shop URL.
• The “Buy now” button stays disabled: the product page has no payment link. The analysis flags it; paste the Stripe, PayPal or Revolut Business link into the product page.
• A variant's button stays disabled: a variant with a different price doesn't inherit the product's link, because the payment provider would charge the wrong amount. Create a separate payment link for it, as the analysis reminds you.
• Products don't appear on the site: neither the product pages nor the Products block are shown as long as the shop is closed.

The complete setup is in Selling with the lightweight shop.

Art direction fonts

An art direction's heading font is downloaded only once by your server, from Fontsource (at cdn.jsdelivr.net), then served by your site. If your host blocks outgoing connections, a message lets you know and the site uses a fallback font from the same family (serif, condensed…). Try again later by saving Settings › Appearance again, or ask your host to allow that address.

Depending on your host

A good part of Éclair CMS troubleshooting depends on what your host allows. The five points to check:

• Hidden files: turn on their display in your FTP client or file manager before uploading Éclair.
• PHP version: you can usually change it in one click in your customer area.
• Outgoing connections: the AI assistant, the art direction fonts, IndexNow and address verification need them.
• Sending emails: some hosts require a sender from the domain or limit mail().
• Nginx: the .htaccess rules must be reproduced in the server configuration.

Each host's specifics are covered in Choosing your hosting and in the universal cPanel, Plesk and DirectAdmin method.