Common Errors in Dolibarr: Causes and Quick Solutions

Table of Contents

1. Introduction

2. Why Understanding Errors in Dolibarr Matters

3. Error Categories in Dolibarr

4. Error #1: “Access Forbidden” or “You Don’t Have Permission”

5. Error #2: “Module Not Found” After Upgrade or Installation

6. Error #3: White Screen or Blank Page

7. Error #4: PDF Generation Fails (TCPDF or DOMPDF Errors)

8. Error #5: SQL or Database Connection Error

9. Error #6: Cron Jobs Not Running

10. Error #7: Timezone or Date Mismatch

11. Error #8: Session Timeout or Automatic Logout

12. Error #9: File Upload or Download Fails

13. Error #10: API Authentication or Token Errors

14. Debugging Tools and Best Practices

15. Final Thoughts

1. Introduction

Dolibarr ERP & CRM is a powerful and modular open-source platform designed to manage everything from invoicing and accounting to HR, inventory, and customer relations. Its simplicity, extensibility, and cost-effectiveness have made it a favorite among SMEs and freelancers worldwide.

However, like any complex web-based system, Dolibarr is not immune to occasional errors, bugs, and misconfigurations. Whether you're a system administrator, developer, or business user, encountering an error can disrupt your workflow and reduce your confidence in the platform.

This article explores the most frequent Dolibarr errors, their underlying causes, and practical, fast solutions. The goal is not only to fix issues but to empower users with a better understanding of how Dolibarr works behind the scenes.

2. Why Understanding Errors in Dolibarr Matters

Mistakes happen—whether during installation, upgrades, configuration, or daily use. Some errors are caused by:

• Server misconfiguration

• File permission issues

• Incompatible modules or templates

• PHP or MySQL version mismatch

• User access rights mismanagement

• Cron or cache problems

The key to efficient troubleshooting is recognizing the error pattern, knowing where to look, and applying the right fix quickly. Learning from these errors also helps prevent future occurrences, increases system uptime, and enhances user trust.

3. Error Categories in Dolibarr

Dolibarr errors generally fall into the following categories:

• Authentication & Permissions: Access denial, login problems

• Module & Plugin Issues: Missing files, incompatible versions

• UI & Rendering: White screens, broken layouts

• Backend/Server: PHP errors, memory limits, database issues

• Cron & Automation: Failed background tasks

• External Tools: PDF generation, file uploads/downloads

• API & Integration: Authentication and connection errors

Let’s now explore the most common individual errors and how to solve them efficiently.

4. Error #1: “Access Forbidden” or “You Don’t Have Permission”

Symptoms:

• Message: “Access forbidden” or “You don’t have permission to access this page.”

• Affects regular users trying to access modules they should have access to.

Causes:

• The user’s role doesn’t have the correct rights assigned.

• The module is disabled or not properly initialized.

• Conflict with custom permissions or third-party modules.

Solutions:

1. Go to Home > Users & Groups > Users > [Select User]

2. Verify that their group has the proper rights under Permissions.

3. Check if the module is enabled in Setup > Modules/Applications.

4. Reinitialize module permissions if custom changes were made.

Quick Tip: Use the admin user to cross-check access and ensure there is no global restriction enabled.

5. Error #2: “Module Not Found” After Upgrade or Installation

Symptoms:

• Error message when accessing a module page

• Missing entries in the module list

• Menus disappear after enabling a module

Causes:

• Improper module folder structure

• Module version is not compatible with current Dolibarr version

• Missing or incorrect module descriptor files (modXXX.class.php)

Solutions:

1. Check if the module is placed in the correct directory:
   /htdocs/custom/[module_name]/

2. Confirm that the module’s main class file is named correctly.

3. Clear Dolibarr cache via Admin > Tools > Clear Cache.

4. If recently upgraded Dolibarr, update the module to a compatible version.

6. Error #3: White Screen or Blank Page

Symptoms:

• A completely blank screen with no error

• Happens after login or when opening certain modules

Causes:

• PHP fatal error (often not displayed due to server settings)

• Memory exhaustion

• Incomplete upgrade

• File permission issues

Solutions:

1. Check your PHP error logs (e.g., /var/log/php/error.log).

2. Enable error display by adding to htdocs/main.inc.php:

   php

   
   

   ini_set('display_errors', 1); error_reporting(E_ALL);

3. Increase memory limit in php.ini:

   ini

   
   

   memory_limit = 512M

4. Re-upload or replace missing or corrupted files.

7. Error #4: PDF Generation Fails (TCPDF or DOMPDF Errors)

Symptoms:

• Invoices or proposals fail to generate PDFs

• Blank PDFs or broken formatting

• Messages like “TCPDF ERROR: Some data has already been output” or DOMPDF exceptions

Causes:

• Corrupted PDF templates

• Output sent before headers

• Missing fonts or incorrect permissions in /documents/ directory

• DOMPDF misconfiguration

Solutions:

1. Switch to a different PDF model in Setup > Dictionaries > Templates

2. Check for accidental whitespace in template PHP files (especially before <?php or after ?>)

3. Set correct permissions on /documents/:

   bash

   
   

   chmod -R 755 /dolibarr/documents/

4. If using DOMPDF, ensure required fonts and PHP extensions are installed.

8. Error #5: SQL or Database Connection Error

Symptoms:

• “Database connection failed” or “SQL error” messages

• Errors appear after migration or configuration changes

Causes:

• Wrong DB credentials in conf.php

• MySQL/MariaDB service down

• Server resource limits (e.g., max connections)

Solutions:

1. Check database status:

   bash

   
   

   systemctl status mysql

2. Open htdocs/conf/conf.php and confirm DB name, user, and password.

3. Test DB credentials manually via CLI:

   bash

   
   

   mysql -u dolibarr_user -p

4. Check logs for failed queries or permission errors.

9. Error #6: Cron Jobs Not Running

Symptoms:

• Scheduled tasks not executed

• Email reminders, recurring invoices, and backups don’t trigger

Causes:

• Cron job misconfigured

• cron.php not reachable due to web server rules

• Script timeouts or permission errors

Solutions:

1. Confirm cron setup with:

   bash

   
   

   crontab -l

   Example cron job:

   bash

   
   

   */10 * * * * wget -qO- https://yourdomain.com/public/cron/cron.php

2. Ensure correct permissions on cron.php (755 or 644).

3. Review cron logs: /var/log/syslog or /var/log/cron.log

4. Use cronjob.class.php logs to debug task execution.

10. Error #7: Timezone or Date Mismatch

Symptoms:

• Incorrect dates in invoices, logs, or calendar entries

• Discrepancies between user input and system storage

• Unexpected behavior when exporting data to external systems

Causes:

• Mismatch between PHP timezone and Dolibarr configuration

• Server using UTC while users expect local time

• MySQL timezone not aligned with PHP

Solutions:

1. In PHP configuration (php.ini), set the correct timezone:

   ini

   CopierModifier

   date.timezone = "Africa/Casablanca"

2. In Dolibarr, confirm timezone under:

   Home > Setup > Misc > Regional Settings

3. Sync MySQL time zone:

   sql

   CopierModifier

   SET GLOBAL time_zone = 'Africa/Casablanca';

4. Restart web and database servers to apply settings consistently.

11. Error #8: Session Timeout or Automatic Logout

Symptoms:

• Users are unexpectedly logged out after short periods

• Sessions don’t persist between tab switches

• “You must log in again” messages appear frequently

Causes:

• Short session timeout in PHP

• Session storage conflicts (especially with multiple users)

• Cache or cookie issues in the browser

• Multiple Dolibarr instances conflicting on the same domain

Solutions:

1. In php.ini, set:

   ini

   CopierModifier

   session.gc_maxlifetime = 3600

2. Enable persistent sessions with proper path settings.

3. Avoid using multiple Dolibarr installs under the same domain without clear cookie separation.

4. Use the Force HTTPS option and enable SameSite=None headers if using secure cookies across subdomains.

12. Error #9: File Upload or Download Fails

Symptoms:

• Can’t upload supplier documents, images, or logos

• Downloads result in empty or corrupted files

• Error: “File not found” or “No file uploaded”

Causes:

• Incorrect file permissions in /documents/ folder

• PHP upload_max_filesize too small

• Temporary folder not writable

• MIME type restrictions or server file limits

Solutions:

1. Set correct permissions on the documents directory:

   bash

   CopierModifier

   chown -R www-data:www-data /dolibarr/documents chmod -R 755 /dolibarr/documents

2. In php.ini, increase limits:

   ini

   CopierModifier

   upload_max_filesize = 20M post_max_size = 25M

3. Confirm that file types are allowed in Dolibarr setup (under module configuration).

4. Test uploads with small files first to rule out other issues.

13. Error #10: API Authentication or Token Errors

Symptoms:

• REST API calls return “Unauthorized” or “Invalid token”

• External integrations fail to connect

• Token expiration issues after short periods

Causes:

• Incorrect API credentials

• Token-based auth not implemented correctly

• API disabled or user permissions too limited

• Misaligned URL or endpoint paths

Solutions:

1. Confirm API is enabled under:

   Home > Setup > Modules > Web services (API)

2. Create a technical user with appropriate API rights.

3. Ensure that the token is passed in the DOLAPIKEY header or query parameter.

4. Use the correct endpoint format:

   ruby

   CopierModifier

   https://yourdomain.com/api/index.php/<resource>?DOLAPIKEY=xxx

5. Enable API debug logs in conf.php by setting:

   php

   CopierModifier

   $dolibarr_main_prod = 0;

6. Validate that the user has access to the module you are trying to query (e.g., invoices, products).

14. Debugging Tools and Best Practices

To handle errors quickly and reduce future problems, implement a proactive debugging and monitoring strategy.

Enable Developer Mode

Add this to htdocs/conf/conf.php:

This displays execution times, SQL queries, and memory usage at the bottom of each page.

Use Error Logs

• PHP Logs: /var/log/php/error.log or php-fpm.log

• Apache Logs: /var/log/apache2/error.log

• Nginx Logs: /var/log/nginx/error.log

• MySQL Logs: /var/log/mysql/error.log

Check these regularly, especially after:

• Module installs

• Dolibarr version upgrades

• Server reconfiguration

Use Git for Customizations

If you're modifying files or custom modules:

• Version them with Git

• Track changes before and after upgrades

• Revert quickly if errors arise

Create a Staging Environment

• Always test new modules, templates, or settings on a copy of your Dolibarr instance

• Use staging to simulate upgrades and find deprecated features

• Use backups (both database and /documents/) before major changes

15. Final Thoughts

Errors are part of any software system, especially in an environment as customizable and modular as Dolibarr. What distinguishes a successful deployment is not the absence of errors, but the ability to resolve them quickly and confidently.

Here’s a quick recap of best practices:

• Understand the source: Is it server, app, user rights, or module related?

• Use logs and debug modes to get meaningful information

• Keep the system lean: disable unused modules and keep your install clean

• Plan for growth: set realistic limits and prepare for more users or records

• Don’t fear errors—document them and integrate them into your IT management strategy

By mastering these common errors and their solutions, you’ll reduce downtime, improve user satisfaction, and maintain a fast, secure, and reliable Dolibarr environment.