Diagnostiquer Dolibarr : support Tutoriel pas à pas en 2026

(Guide complet pour administrateurs, développeurs et utilisateurs finaux)

Note : Ce tutoriel s’appuie sur Dolibarr ERP/CRM version 2026.2 (stable) et suppose que vous disposez d’un serveur Linux (Debian 12 / Ubuntu 24.04) ou Windows Server 2022, d’un accès à la base de données et des droits d’administration.

1. Introduction : Pourquoi un « Diagnostic » dédié à Dolibarr ?

Dolibarr est un ERP / CRM open‑source très répandu, mais sa modularité (modules comptabilité, stocks, ventes, etc.) peut rendre la panne d’un composant source de confusion. En 2026, les environnements de déploiement sont de plus en plus hétérogènes : conteneurs Docker, serveurs « bare‑metal », plateformes cloud (Azure, AWS, Google Cloud) ou solutions hybrides.

Un processus de diagnostic structuré permet :

  • D’identifier rapidement la cause racine d’un dysfonctionnement (erreur PHP, problème de base de données, conflit de module, etc.).

  • De réduire le temps moyen de réparation (MTTR) de plusieurs heures à quelques minutes.

  • D’assurer la continuité de service pour les PME/ETI qui dépendent de Dolibarr pour leurs flux critiques.

Ce guide vous propose un tutoriel pas à pas pour diagnostiquer, isoler et corriger les pannes les plus courantes de Dolibarr en 2026.

2. Principaux scénarios de panne à anticiper

Symptomome Déclencheur fréquent Impact potentiel
Page blanche / « 500 Internal Server Error » Mise à jour de module / changement de PHP version Interruption totale du site
Erreur « Class not found » Module désactivé ou absent Fonctionnalité manquante (ex. : paiement)
Connexion à la base MySQL/MariaDB échoue Wrong credentials, version incompatibile, timeout Aucun accès aux données
Symptômes de lenteur / timeout Requêtes SQL lourdes, cache désactivé, serveur sous‑dimensionné Temps de réponse > 5 s
Erreurs de cron (jobs automatiques) Crontab mal configuré, timezone Émission de factures, stock non mis à jour
Module qui ne charge pas après migration Table de métadonnées corrompue Découpage de droits, perte de fonctionnalités
Messages « Permission denied » sur les dossiers Droits Unix incorrects, SELinux/AppArmor Impossible de créer/éditer des fichiers

3. Prérequis avant de commencer le diagnostic

Outil Règle Commande (Linux)
PHP Version ≥ 8.1 (Dolibarr 2026.2 requiert PHP 8.1‑8.3) php -v
Web server Apache 2.4+ ou Nginx 1.23+, avec module mod_rewrite activé apache2ctl -M ou nginx -V
Database MySQL 8.0 / MariaDB 10.6 ou supérieure mysql --version
Composer Pour les mises à jour de dépendances (facultatif) composer --version
Cron Service actif (systemctl status cron ou systemctl status crond) —
Permissions Répertoire Dolibarr writable par le serveur web (www-data, nginx, apache) chmod -R 775 /var/www/dolibarr && chown -R www-data:www-data /var/www/dolibarr
Backup Toujours disposer d’une sauvegarde récente (dump SQL + copie du répertoire htdocs) mysqldump -u root -p dbname > db.sql

Astuce 2026 : Si vous déployez Dolibarr dans un conteneur Docker, ajoutez le flag --restart unless-stopped et montez les volumes ./data:/var/www/dolibarr afin de préserver les données.

4. Étape 1 – Vérifier l’environnement d’exécution

4.1. Diagnostic PHP

# Affiche les informations PHP utilisées par le serveur web

php -i | grep -E 'Version|Loaded Configuration|date.timezone'

  • Checklist :

    • PHP Version => 8.2.x (ou 8.3).

    • Extensions obligatoires : pdo_mysql, gd, intl, openssl, zip, exif, fileinfo.

    • date.timezone doit être défini sur votre fuseau horaire (ex. Europe/Paris).

4.2. Vérifier les modules actifs

Dans le fichier conf/perso.conf.php (ou via l’interface Dolibarr > Administration > Configuration > Serveurs), assurez‑vous que les modules requis sont activés :

Module Fonction Activation
agcurl communications externes (API, paiement) extension=curl
agpgsql PostgreSQL (optionnel) extension=pgsql
aglibpdf génération de PDF extension=pdf
agmemcache cache HTTP extension=memcache

Si une extension manque, installez‑la puis redémarrez le serveur web. 

apt-get install php8.2-curl php8.2-gd php8.2-intl php8.2-zip

systemctl restart apache2   # ou php-fpm

4.3. Test de connexion à la base de données

mysql -u dolibarr_user -p -h localhost dolibarr_db

Erreurs fréquentes

  • Access denied → credentials erronés ou privilèges insuffisants. – Host ‘XYZ’ is blocked → le serveur MySQL est configuré avec bind-address. Modifiez my.cnf (bind-address = 0.0.0.0 ou adresse IP autorisée).

5. Étape 2 – Analyser les logs serveur & Dolibarr

Dolibarr écrit dans dolibarr/log (ou logs/ selon la version). Les fichiers clés sont :

Fichier Contenu Lecture recommandée
errors.log Exceptions PHP, warnings, notices tail -f errors.log
cron.log traces des jobs CRON cat cron.log
install.log historique de l’installation cat install.log

5.1. Recherche d’erreurs critiques (« Fatal error », « Class not found », « Catchable fatal error »)

grep -i "Fatal\|Catchable\|Class not found" -R dolibarr/log/* | sort -u > /tmp/fatal_errors.txt

Si le fichier ne contient aucune entrée, le problème vient souvent d’un serveur HTTP trop restrictif (ex. php_admin_flag désactivée).

5.2. Le rôle du mode débogage

Ajoutez dans htdocs/conf/perso.conf.php :

$conf['debug'] = 1;          // 0 = désactivé, 1 = mode debug

$conf['debugsql'] = 1;       // log des requêtes SQL

Redémarrez le serveur, rechargez la page puis relisez les logs.

Tip 2026 : le debugsql est indispensable pour identifier les requêtes lentes qui ne figurent pas dans le slow_query_log de MySQL.

6. Étape 3 – Vérifier la santé de la base de données

6.1. Vérifications MySQL« `sql

— 1. Vérifier la version
SELECT VERSION();

— 2. Inspecter la taille des tables (problème de fragmentation)
SELECT table_name, engine, rows, data_length/(1024*1024) AS mb FROM information_schema.tables WHERE table_schema=’dolibarr_db’;

— 3. Détecter les tables corrompues
SELECT table_name FROM information_schema.tables WHERE engine=’InnoDB’ AND check_table = ‘corrupt’;



*Si des tables sont marquées comme **corrompues**, exécutez immédiatement :*
```sql

ALTER TABLE `nom_de_la_table` REPAIR;

6.2. Analyse de la lenteur

Activez le slow_query_log (si non déjà présent) :

slow_query_log = 1

slow_query_log_file = /var/log/mysql/slow.log

long_query_time = 2

Inspectez les requêtes qui dépassent 2 s. 

mysqldumpslow -s t -t 10 /var/log/mysql/slow.log

Solution typique : ajouter des index (ALTER TABLE ... ADD INDEX (...)) ou optimiser le code PHP qui invoque ces requêtes. —

7. Étape 4 – Diagnostiquer les problèmes de module / extensionDolibarr propose plus de 150 modules (stocks, factures, paiement, etc.). Chaque module possède son propre répertoire htdocs/<module>/.

7.1. Lister les modules désactivés

find htdocs -maxdepth 1 -type d -name "mod*" | grep -v -E 'mod_(users|hooks|core)' | xargs ls -l

Vérifiez le fichier modxxx.conf.php pour le champ enabled. Exemple :

$modconf['modstock'] = array('enabled' => 1);

7.2. Désactiver/ réactiver un module via la console

php -r "require_once('htdocs/cfg/class/PMessage.class'); $dm = new Msg('invoice'); $dm->disableModule('modinvoice');"

Ensuite, rafraîchissez l’interface d’administration pour confirmer que le module repasse à « désactivé ».

7.3. Conflit de nom de classe

Parfois, deux modules déclarent la même classe (ex. class FrontController). Le log vous affichera :

Fatal error: Class 'FrontController' already has been defined

Solution : renommez le namespace du module ou désactivez le module en conflit.

8. Étape 5 – Résoudre les problèmes de permissions et de sécurité

Symptomome Cause fréquente Fix
Permission denied lors de création d’un document PDF Le dossier tmp/ n’est pas écriturable chmod 775 /var/www/dolibarr/tmp && chown www-data:www-data /var/www/dolibarr/tmp
Erreur mod_security bloque les requêtes POST ModSecurity dans son mode paranoïaque bloque l’URL contenant php Désactiver temporairement ou ajouter une règle SecRuleRemoveById 950125
Accès refusé sur /var/www/dolibarr/htdocs SELinux/AppArmor en enforcing setsebool -P httpd_can_network_connect_db on ou aa-complain /etc/apparmor.d/usr.sbin.apache2

2026 : La plupart des déploiements Docker utilisent docker-compose avec les options security_opt: "no-new-privileges"; assurez‑vous que le volume Docker est monté en rw (Z ou z pour SELinux).

9. Étape 6 – Déployer ou restaurer à partir d’un backup

9.1. Sauvegarde automatisée ( recommandé 2026 )

#!/bin/bash

# backup_dolibarr.sh

DATE=$(date +%Y%m%d_%H%M)

BACKUP_DIR="/backups/dolibarr"
# 1. Dump SQL

mysqldump -u $DB_USER -p$DB_PASS $DB_NAME > $BACKUP_DIR/dolibarr_$DATE.sql
# 2. Archive du code

tar -czf $BACKUP_DIR/dolibarr_code_$DATE.tar.gz -C /var/www/dolibarr htdocs
# 3. Retention 30 jours

find $BACKUP_DIR -type f -mtime +30 -delete

Ajoutez-le à cron.daily pour automatiser.

9.2. Restauration rapide

# 1. Restaurer la base

mysql -u $DB_USER -p$DB_PASS $DB_NAME < /backups/dolibarr_20260801.sql
# 2. Décompresser le code

tar -xzf /backups/dolibarr_code_20260801.tar.gz -C /var/www/dolibarr
# 3. Vérifier les permissions

chown -R www-data:www-data /var/www/dolibarr

chmod -R 775 /var/www/dolibarr/tmp /var/www/dolibarr/blankconf

10. Étape 7 – Optimisations & prévention des pannes futures

Action Description Fréquence
Mise à jour régulière Releases de sécurité (Dolibarr 2026.x) et des extensions PHP Tous les 3 mois
Scan de vulnérabilités Utilisez Trivy ou OWASP ZAP sur l’image Docker Mensuel
Surveillance de la charge Grafana + Prometheus (metrics PHP-FPM, MySQL Queries_per_second) Continue
Alertes cron Script check_dolibarr.sh qui teste l’accès à une URL interne (/index.php?main=dashboard) et envoie un email si KO Hebdomadaire
Nettoyage du cache Supprimez régulièrement dolibarr/datacache/ si le système de cache (APCu, Redis) devient plein Mensuel
Documentation des changements Versionnez conf/*.conf.php dans Git (ou GitLab) pour traçabilité À chaque modification

11. Checklist finale – « C’est bon ? »

Après avoir passé les étapes précédentes, assurez‑vous que les points suivants sont validés :

✅ Vérification
✔️ PHP ≥ 8.1, toutes les extensions requises activées
✔️ La connexion à la BDD fonctionne (USER/PASS, host)
✔️ Aucun Fatal error dans errors.log après activation du mode debug
✔️ Les permissions du répertoire dolibarr/tmp sont 775 et le propriétaire est l’utilisateur web
✔️ Tous les modules nécessaires sont activés dans conf/perso.conf.php
✔️ Les scripts CRON s’exécutent sans erreur (cron.log propre)
✔️ Les tests d’URL interne (/index.php?main=setup) renvoient 200 OK
✔️ La sauvegarde récente a pu être restaurée sur un serveur de test
✔️ Les métriques (CPU, RAM, IO) sont dans la fourchette attendue (ex. < 40 % RAM, < 500 ms temps de réponse)

Si tout est coché, votre instance Dolibarr devrait fonctionner de façon stable pour les mois à venir.

12. Conclusion

Diagnostiquer Dolibarr en 2026 ne consiste plus simplement à lire les messages d’erreur ; il s’agit d’une méthodologie complète qui mêle :

  • Système (PHP, base de données, permissions).

  • Application (modules, configuration, logs).

  • Opérations (monitoring, backup, mise à jour).

En suivant scrupuleusement le tutoriel pas à pas présenté ci‑dessus, vous serez en mesure de :

  • Isoler rapidement la cause d’une panne.

  • Appliquer la correction adéquate (patch, re‑indexation, ajustement de configuration).

  • Prévenir la récurrence du problème grâce à des contrôles automatisés. N’hésitez pas à documenter chaque incident dans votre système de tickets (ex. : GitLab Issues, Jira) en joignant les logs et le traceback exact, afin de créer une base de connaissances reusable pour votre équipe.

Bonne résolution de pannes ! 🚀 —

Article rédigé par l’équipe de support Dolibarr – version 2026.2 – pour les utilisateurs francophones.

Publications similaires