---
title: "Troubleshooting"
description: "Éclair CMS troubleshooting: forgotten password, installation locked, 404 or 500 error, unconverted images, missing emails, debug mode, proxy."
url: "https://eclaircms.org/en/documentation/troubleshooting"
lang: "en"
author: "Thierry Gustin"
published: "2026-10-30"
updated: "2026-10-30"
---

# Troubleshooting

> **Key takeaways** — This Éclair CMS troubleshooting guide gives the fix for the most common problems: a forgotten password or lost 2FA phone (data/reset.php file), installation locked after 2 hours, a 404 error caused by a missing .htaccess, a 500 error, images not converted to WebP, contact form emails not arriving, debug mode and IP addresses skewed by a proxy.

This Éclair CMS troubleshooting guide brings together the most common problems and their fixes, from a forgotten password to a 404 error. Each section matches a specific message or symptom: use the table of contents to jump straight to yours. Most take two minutes to fix, with your FTP client or your host’s file manager.

## Forgot your password or lost your two-factor authentication phone?

Start with the simplest solutions:

- **There’s another administrator**: in Users, they can click **Reset password** (a temporary password is created) or **Disable 2FA** on your account.
- **You lost your phone, not your codes**: log in with one of your 8 backup codes instead of the 6-digit code.

If you’re the only administrator, use the FTP recovery. Create a `data/reset.php` file containing exactly these three lines:

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

Within 24 hours, **log in with that email and that new password**. The password is replaced, two-factor authentication for that account is turned off, your other sessions are closed and the file is deleted automatically.

> **Why it’s safe** — Nobody else can trigger this recovery: it takes FTP access to drop the file, and knowledge of its contents to use it. A file without the first line is refused and deleted. The new password must follow the usual rules: 10 characters minimum, no overly common password.

## “Installation locked”: what should you do?

For security, the installation must be completed **within 2 hours** of the first visit: otherwise, anyone could take over a site that was uploaded and then forgotten. Once that window has passed, delete the `data/install-window.php` file via FTP, then reload the page: a new 2-hour window opens.

## Site address not verified on the Security page: what does it mean?

Your server can’t reach itself at the site’s address: host firewall, DNS not propagated yet, domain being transferred… The site works normally, but without redirects to the official address (with or without www, http to https). Click **Verify the site address** once the domain is in place.

## Why is there a 404 error on every page except the homepage?

The `.htaccess` file wasn’t uploaded, because it’s a hidden file, or URL rewriting is disabled. Turn on “Show hidden files” in your FTP client and upload the file again to the site’s root. If your host requires it, uncomment the `RewriteBase /` line in `.htaccess`.

> **The installer’s diagnosis** — During installation, the “Clean URLs (URL rewriting)” line already tells you whether `.htaccess` works. On Nginx, which ignores this file, copy the configuration from the [For developers](https://eclaircms.org/en/documentation/developers) guide.

## What should you do about a 500 error right after uploading?

Your host rejects a `.htaccess` directive. That’s very rare: only directives that shared hosting accepts are used. Remove the block in question or contact your host. If a page saying “Oups, un court-circuit.” (French for “Oops, a short circuit”) appears with a reference, the error details are in **Security › Recent technical errors**.

## Why aren’t images converted to WebP?

The PHP GD extension, or its WebP support, is missing on your hosting. Enable it in your host’s PHP panel. In the meantime, your images stay in JPG or PNG: the site works, it’s just a little less lightweight.

## Why am I not receiving emails from the contact form?

Don’t panic: messages are also saved in the admin, under **Messages**. Then check the **Receive messages at** address in **Settings › Contact**; by default, it’s the first administrator’s email. Some hosts require the sender to belong to the site’s domain: create an email address on your domain if needed.

## How do you turn on debug mode?

Create an `eclair-config.php` file at the root of the site, next to `index.php`, based on `eclair-config.exemple.php`:

```php
<?php
defined('ECLAIR') || exit;

// Show error details while you solve the problem.
define('ECLAIR_DEBUG', true);
```

Errors are then shown in detail and the static cache is turned off. **Delete this file as soon as the problem is solved**: error details shouldn’t be visible to everyone.

## All IP addresses are the same: is your site behind a proxy?

If the security log shows the same IP address for every visitor, your site is probably served behind a proxy or a CDN, such as Cloudflare. The attempt limits, which apply per network, then hit everyone at once. In **Settings › Advanced › “Site behind a proxy / CDN”**, choose the header that passes on the real address: `CF-Connecting-IP` for Cloudflare, `X-Forwarded-For` or `X-Real-IP` depending on your host.

> **Only if you need it** — Leave “No (recommended)” if your site isn’t behind a proxy: otherwise, a visitor could supply a fake IP address. Éclair only reads the last address in the header, the one added by the proxy.

## Does Éclair say it needs PHP 8.1 or later?

If the page shows “Éclair a besoin de PHP 8.1 ou plus récent” (French for “Éclair needs PHP 8.1 or later”), your hosting uses a PHP version that’s too old. Change it in your host’s customer area, often in one click, then reload the page. Éclair runs on PHP 8.1 to 8.5; choose 8.3 or later if you can. The [Install Éclair on o2switch](https://eclaircms.org/en/installation/o2switch) guide shows where this setting is in cPanel.

## Is the AI assistant not responding?

Key rejected, out of credit, monthly budget used up, outgoing connections blocked: each message has its fix in the [AI assistant](https://eclaircms.org/en/documentation/ai-assistant#if-the-assistant-does-not-respond) guide.

## Is your problem missing from this Éclair CMS troubleshooting guide?

Write down the exact error message, your host and your PHP version, then write to me through the [Contact](https://eclaircms.org/en/contact) page. You can also report a problem on [GitHub](https://github.com/Jacckisback/eclair-cms/issues): its fix will make this Éclair CMS troubleshooting guide better for every user.

## Troubleshooting questions

### Does the data/reset.php file work if I turned on two-factor authentication?

Yes. Logging in with the email and new password from the file turns off two-factor authentication for that account. Turn it back on afterwards in My profile.

### Where do I find hidden files like .htaccess?

In your FTP client, turn on the “Show hidden files” option. In the cPanel File Manager, it’s under Settings › “Show Hidden Files (dotfiles)”.

### How do I find out which error occurred?

Open Security › Recent technical errors, or temporarily turn on debug mode with an eclair-config.php file. Remember to delete it afterwards.

### My site shows a blank page: where do I start?

Check the PHP version (8.1 minimum), then turn on debug mode to display the error. In most cases, a file or a PHP extension is missing.