Version November 2025 – Guide pratique pour les utilisateurs et les administrateurs
1. Introduction
Dolibarr est un ERP/PGI (Enterprise/Business Management) open‑source destiné aux PME et aux auto‑entrepreneurs. Sa modularité repose sur plus de 50 modules (ex. : Factures, Devis, Stocks, CRM, Bibliothèques, etc.) qui peuvent être actifs ou désactivés à la volée.
Cependant, la flexibilité de la plateforme implique souvent que des utilisateurs rencontrent des difficultés pour :
- identifier quel module cause un dysfonctionnement,
- configurer correctement les paramètres,
- déboguer les messages d’erreur,
- migrer des données entre versions.
Ce guide propose une FAQ ciblée pour chaque module le plus utilisé, accompagnée d’exemples concrets de diagnostic et de résolution. Vous pouvez copier‑coller les tableaux de “symptôme ↔ cause ↔ solution” dans votre wiki interne.
2. Méthodologie de diagnostic général
| Étape | Action | Résultat attendu |
|---|---|---|
| 2.1 | Activer le mode débogage ($conf['debug'] = true;) dans conf/conf.php. |
Les messages d’erreur plus détaillés s’affichent (ex. : SQL Error : …). |
| 2.2 | Examiner le journal de serveur (error_log, access_log). |
Corroborer les messages de Dolibarr avec les requêtes SQL ou les warnings PHP. |
| 2.3 | Vérifier les droits d’accès (droits Linux sur les dossiers files/, photos/, pdf/, cache/). |
Aucun fichier inaccessible → éviter “Permission denied”. |
| 2.4 | Faire un “self‑test” via http://yourhost/dolibarr/index.php?mainpage=selfcheck. |
Affichage d’un rapport complet des dépendances PHP et des modules requis. |
| 2.5 | Reproduire le problème avec un compte test pour isoler le côté front‑office ou back‑office. | Déterminer si le bug vient du formulaire, du processus asynchrone ou d’une donnée corrompue. |
Astuce : Sauvegarder toujours la base avant d’appliquer des correctifs massifs (
phpMyAdmin → Export → SQL).
3. FAQ des modules les plus rencontrés
3.1 Module Factures / Devis
| Problème fréquent | Symptôme | Cause la plus fréquente | Solution concrète (exemple) |
|---|---|---|---|
| Facture vide après validation | La facture apparaît sans lignes ni totaux, le montant reste à 0,00 €. | dolibarr_cart n’est pas initialisé (session non valide) ou le champ price est nul dans le formulaire. |
1️⃣ Vérifier que le champ price est renseigné dans le formulaire. 2️⃣ Dans htdocs/core/classes/cart.class.php, ajouter avant le calcul du total : if (empty($this->products)) { $this->initFromRequest(); } 3️⃣ Vider le cache : rm -rf /var/www/html/dolibarr/cache/*. |
| “Erreur lors du envoi du mail” | Message : “Error while sending email” même si le serveur mail est configuré. | mail() ou sendmail_path renvoie “No such file or directory” (path manquant ou permission). |
1️⃣ Ajouter dans conf/conf.php :$conf['mail_type'] = 'tnt'; // ou 'smtp' si vous l’utilisez 2️⃣ Tester l’appel : php -r 'mail("test@example.com","test","body","From: admin@domain.tld");' 3️⃣ Corriger la variable $mailpath dans php.ini ou installer ssmtp. |
| Lien PDF de facture renvoie 404 | Le PDF n’est jamais généré, le lien comme .../upload/tmp/facture_123.pdf n’existe pas. |
Le répertoire pdf n’est pas ajouté à $conf['document_dir'] ou la fonction GD n’est pas installée. |
Ajouter dans conf/conf.php :$conf['document_dir'] = '/var/www/html/dolibarr/files; Vérifier l’extension gd : php -m | grep gd. Si absent, installer : sudo apt-get install php-gd puis redémarrer Apache. |
| Duplication de lignes factures après refresh | Plusieurs lignes avec même libellé et même prix apparaissent. | Le navigateur envoie le formulaire en double (double‑clic ou soumission AJAX non annulée). | Implémenter un token CSRF dans le formulaire (déjà présent par défaut). En mode dev, désactiver le cache du navigateur ( Ctrl+Shift+R). |
3.2 Module Clients / Vendeurs
| Problème | Symptôme | Cause | Solution concrète |
|---|---|---|---|
| Le champ “Email” reste vide après création | L’adresse email n’est pas stockée, mais le nom apparaît. | Table llx_customers – colonne email non remplie à cause d’un trigger qui écrase les valeurs. |
1️⃣ Ouvrir htdocs/business/boxes/functions_customer.inc.php et vérifier la fonction addCustomer. 2️⃣ Corriger l’appel : $this->email = $freo; (au lieu de $this->email = $contact["email"];). |
| “Dernier contact” affiché comme “null” | Aucun historique de communication. | La fonction get_connections ne récupère pas les enregistrements dans llx_sochistory en raison d’un filtre de date mal formé. |
Modifier la requête :WHERE hid_date >= '".$conf->max_date."' AND hid_user_id = ".$user->id; → $conf->max_date doit être format YYYY-MM-DD H:i:s. |
| Import CSV déforme les accents | Les noms avec œ, é apparaissent comme é. |
Encodage UTF‑8 non reconnu lors du parsing ($line[0]). |
Dans htdocs/business/import/csvimport.class.php ajouter :iconv_set_flags('IGNORE', 'UTF-8'); avant la boucle de lecture. |
3.3 Module Stocks / Entrées/Sorties
| Problème | Symptôme | Cause | Solution concrète |
|---|---|---|---|
| Quantité en stock toujours 0 même si des entrées ont été créées | La somme des mouvements indique 0, alors que la ligne d’entrée a bien été saisie. | Le paramètre USE_QUANTITY n’est pas activé dans le module Stock (défaut désactivé). |
1️⃣ Activer le suivi de quantités : $conf->global->set('USE_QUANTITY', 1); 2️⃣ Recalculer les stocks : php -f /var/www/html/dolibarr/talang/autoload.php?module=stock. |
| Erreur de doublon lors de l’ajout d’un article à la liste d’entrée | “Duplicate entry ‘10-100’ for key ‘PRIMARY’” | Deux lignes d’entrée utilisent le même ID_RCR (réference) mais avec différents ref_ext. |
Vérifier dans htdocs/suppliers/books/books.php que le champ ref_ext est unique par fournisseur. Normaliser le format : $line['ref_ext'] = strtoupper(str_replace(' ', '_', $line['ref_ext']));. |
| Le rapport de rupture de stock n’affiche aucune ligne | Aucun article n’est marqué comme “Rupture de Stock” alors qu’il y a des seuils configurés. | La fonction get_stock_balance ne tient pas compte du champ “seuil”. |
Modifier get_stock_balance dans categories/class/category.class.php : $bal = $product->quantities[$product->id]; → if ($product->minimums > 0 && $bal < $product->minimums) $this->stock_alert = 1;. |
3.4 Module CRM / Prospects | Problème | Symptomome | Cause | Solution concrète |
|———-|————|——-|——————-|
| Le suivi des actions ne s’enregistre jamais | Aucun enregistrement dans llx_calls ni dans l’onglet “Calls”. | calls module désactivé dans conf/conf.php ( $conf->enable_module('calls'); manquant). | Activer le module :$conf->enable_module('calls');
Recompiler les menus : php -f /var/www/html/dolibarr/talang/autoload.php?module=calls. |
| Losang “Prospect” affiché en rouge alors qu’il ne doit pas l’être | Le groupe “Prospect” possède le même ID que “Client”. | Dans htdocs/crm/dolibarr.php le mapping du groupe ($groupid) utilise la mauvaise clé d’index ('prospect' au lieu de $conf->global->get('CRM_PROSPECT_GROUP')). | Corriger le fichier :$groupid = $conf->global->get('CRM_PROSPECT_GROUP');
Vérifier la valeur dans la base : SELECT id FROM llx_user_category WHERE label='Prospect';. |
| Recherche par email renvoie plusieurs résultats inexacts | La requête SQL n’utilise pas de LIKE avec LOWER(). | La fonction findprospectsbyemail utilise directement $pdo->query("SELECT ... WHERE email = '$email'");. | Utiliser une recherche insensible à la casse :WHERE LOWER(email) LIKE CONCAT('%', LOWER('". $db->quote($email) ."'), '%'). |
3.5 Module Bibliothèque (Docs & URL)
| Problème | Symptome | Cause | Solution concrète |
|---|---|---|---|
| Les documents PDF ne s’affichent pas via le preview | Le lien index.php?mainpage=phptohtml génère une page blanche. |
Plugin GD non installé ou imagemagick manquant. |
installer sudo apt-get install php-imagick imagemagick et activer extension=imagick.so dans php.ini. |
| Erreur “File not found” sur le fichier uploaded depuis le navigateur mobile | Le chemin du fichier résout en /var/www/html/dolibarr/tmp/ alors que les fichiers sont dans /tmp/. |
document_dir pointe vers un répertoire relatif qui change selon le docroot. |
Modifier conf/conf.php en utilisant un chemin absolu :$conf['document_dir'] = '/home/dolibarr/dolibarr/files/'; |
URL rewriting impossible → toutes les pages reviennent à index.php?... |
Le serveur Apache ne possède pas de mod_rewrite actif. |
Apache non configuré pour réécrire les URLs. | Activer le module : sudo a2enmod rewrite puis sudo systemctl reload apache2. Dans le VirtualHost, ajouter : AllowOverride All. |
4. Cas d’usage complet : “Facture d’un nouveau client ne génère pas de PDF”
4.1 Scénario
- Création d’un client dans le module Clients → aucun problème.
- Création d’un devis (module Devis) → OK. 3. Transformation du devis en facture → clique sur “Convertir en facture”.
- La facture apparaît dans la liste, mais le lien “PDF” donne 404.
4.2 Diagnostic pas à pas | Étape | Action | Observation | Interprétation |
|——|——–|————-|—————-|
| 1 | Ouvrir dolibarr/logs/dolibarr.log (ou error.log). | PHP Warning: file_get_contents(/var/www/html/dolibarr/files/PDF/facture_567.pdf): failed to open wrapper 'files'://var/www/html/dolibarr/files/... | Le chemin utilisé ne correspond pas au répertoire réel. |
| 2 | Vérifier $conf['document_dir'] dans conf/conf.php. | $conf['document_dir'] = '/home/dolibarr/dolibarr/files/'; | Le répertoire défini n’est pas sous htdocs → les scripts d’accès HTTP ne le voient pas. |
| 3 | Ajouter error_reporting(E_ALL); dans index.php. | Le warning devient visible : document_dir mal initialisé à la création du fichier. | Au moment de la création du PDF, le script utilise $pdf->create($conf['document_dir']); mais conf['document_dir'] n’est pas encore chargé (appel avant inclusion). |
| 4 | Forcer le répertoire absolu dans htdocs/core/fpdf/fpdf.php (ligne 145). | Modifier public static function defaultdocpath = '/var/www/html/dolibarr/files/'; | Le PDF se crée dans le bon dossier. |
| 5 | Recharger la page → le lien PDF fonctionne. | Le fichier facture_567.pdf apparaît dans /var/www/html/dolibarr/files/PDF/. | Problème résolu. |
4.3 Cran de résolution (patch)
// File: htdocs/conf/conf.php, ligne 42 (ou votre version)
-$conf['document_dir'] = '/home/dolibarr/dolibarr/files/';
+// Force le chemin absolu à partir du répertoire du projet
+$conf['document_dir'] = dirname(__FILE__) . '/../..';
+$conf['document_dir'] .= '/files/'; // => /var/www/html/dolibarr/files/Note : Après modification, videz le cache (
rm -rf /var/www/html/dolibarr/cache/*) et relancezapachectl graceful.
5. Outils complémentaires pour le diagnostic avancé
| Outil | Usage | Commande / Installation |
|---|---|---|
| phpMyAdmin → Export → SQL | Exporter la structure avant modification | php -r "require('bootstrap.php'); \$db->dumpTable('llx_categorie');" |
| Valgrind + Xdebug | Analyser les appels de fonctions lents (paged rendering) | sudo apt-get install xdebug && php -d xdebug.profiler_enable=1 script.php |
Symfony VarDumper (dans dolibarr/modules.php) |
Affiche la valeur d’une variable en temps réel | var_dump($myVar); ou dump($myVar); |
| Dockerised dev environment | Reproduire exactement le même environnement que le serveur de prod | docker-compose up -d && docker-compose exec php bash |
| php -l | Vérifier la syntaxe du fichier modifié avant déploiement | php -l htdocs/business/xxx.php |
6. Bonnes pratiques pour éviter les bugs futurs
- Versionner les fichiers de configuration (
conf/*.php) avec Git, même si ce sont des fichiers non‑code. - Utiliser des environnements de test identiques à la prod (même version PHP, même extensions).
- Ne jamais désactiver
$conf['debug']en production : un simple?debug=1expose les stack‑traces sans laisser le site ouvert. - Sémantique des noms de modules : chaque module possède un préfixe unique (
llx_). Ne pas créer de nouveaux dossiers avec des noms qui collident. - Sauvegardes automatisées : script
cronqui exporte la base chaque nuit et déplace les fichiers dans/backup/dumps/. - Documentation des override : chaque fichier dans
/custom/doit contenir un header :/**
* Override : improves PDF generation for invoices.
* Author: Jean Dupont, 2025‑10‑15 */
7. Conclusion
Diagnostiquer un problème dans Dolibarr, c’est avant tout *comprendre la façon dont les modules interagissent avec le noyau (dol_core, `llx_` tables) et tirer profit des outils de débogage** que la plateforme met à disposition.
Le tableau de la section 3 fournit une FAQ prête à l’emploi pour les modules les plus sensibles (Factures, Stocks, CRM, etc.). En suivant la méthodologie de la section 2 et en appliquant les résolutions concrètes proposées, vous pourrez :
- identifier rapidement la cause racine,
- appliquer un correctif ciblé (patch ou configuration),
- vérifier que le problème persiste ou a été résolu,
- documenter l’incident pour les futures interventions.
En combinant ces pratiques avec les outils avancés listés en section 5, vous disposerez d’une chaîne de diagnostic robuste capable de gérer même les scénarios les plus complexesMeet Dolibarr-Faq- Module Diagnosis.
Bonne chasse aux bugs ! 🎯