Table of Contents

  1. Introduction

  2. Why Dolibarr Errors Happen

  3. How to Approach Troubleshooting Effectively

  4. Common Error Categories

    • 4.1 Installation and Configuration Errors

    • 4.2 Database Connection Issues

    • 4.3 Login and Access Problems

    • 4.4 Module Activation Failures

    • 4.5 PDF Generation Errors

    • 4.6 Email Sending Failures

    • 4.7 Update and Upgrade Problems

    • 4.8 API and Webhook Failures

    • 4.9 File Permissions and Upload Errors

  5. Tools for Diagnosing Dolibarr Issues

  6. Error Logs: Where to Find and How to Read Them

  7. Step-by-Step Troubleshooting Examples

    • 7.1 Error: "Cannot Connect to Database"

    • 7.2 Error: "Access Forbidden - Token Expired"

    • 7.3 Error: "PDF not Generated"

    • 7.4 Error: "SMTP Connection Failed"

    • 7.5 Error: "Module Won’t Activate"

  8. Best Practices for Preventing Errors

  9. When to Ask for Community or Developer Support

  10. Backup and Restore Tips Before Debugging

  11. Hosting and Environment Considerations

  12. Using the Dolibarr Forum for Solutions

  13. How to Create a Bug Report for Developers

  14. Useful Configuration Parameters

  15. Tips for Stable Upgrades

  16. Managing Third-Party Modules and Compatibility

  17. Real Business Scenarios and How They Were Solved

  18. Documenting Your Error Resolutions Internally

  19. Resources and References

  20. Conclusion

1. Introduction

Even with its robust architecture and active community, Dolibarr ERP & CRM users occasionally encounter errors. These may be caused by misconfigurations, server issues, outdated modules, or permissions. The good news? Most of these errors have simple and effective solutions.

This guide offers a hands-on, illustrated walk-through of the most common Dolibarr errors in 2025 and how to solve them quickly.

2. Why Dolibarr Errors Happen

Dolibarr, being modular and self-hosted (or cloud-based), depends on many external factors:

  • Server configurations (PHP version, MySQL limits)

  • File permissions

  • User access rights

  • Third-party module compatibility

  • Improper updates or installations

Understanding these variables can help narrow down the issue faster.

3. How to Approach Troubleshooting Effectively

  • Start by replicating the error

  • Use logs for context

  • Disable recent changes to identify causes

  • Always test fixes in a staging environment

  • Document each step for future reference

4. Common Error Categories

4.1 Installation and Configuration Errors

Wrong PHP settings or missing modules often cause white screens or 500 errors during installation.

4.2 Database Connection Issues

Incorrect database name, credentials, or port settings are the usual suspects.

4.3 Login and Access Problems

Session expiry, browser cache, and token mismatch can block access.

4.4 Module Activation Failures

Happens when dependencies are missing or file permissions are incorrect.

4.5 PDF Generation Errors

Caused by TCPDF issues, wrong permissions, or broken logos in templates.

4.6 Email Sending Failures

Usually linked to SMTP misconfiguration or blocked ports.

4.7 Update and Upgrade Problems

Incompatible versions or missed migration steps can corrupt the install.

4.8 API and Webhook Failures

Often due to authentication errors, CORS issues, or improper payload formats.

4.9 File Permissions and Upload Errors

Files and directories may lack write/read permissions, especially after migration.

5. Tools for Diagnosing Dolibarr Issues

  • Dolibarr logs (htdocs/documents/dolibarr.log)

  • PHP error logs

  • Apache/Nginx logs

  • Browser console

  • SQL database query logs

6. Error Logs: Where to Find and How to Read Them

Logs typically provide:

  • File path of the error

  • Timestamp

  • Description of the error

Use tools like Notepad++, tail -f in Linux, or log analyzers.

7. Step-by-Step Troubleshooting Examples

7.1 Error: "Cannot Connect to Database"

  • Check conf.php for correct credentials

  • Ensure MySQL is running

  • Verify port and host

7.2 Error: "Access Forbidden - Token Expired"

  • Clear browser cache

  • Log out and back in

  • Ensure sessions are not interrupted by proxies or firewalls

7.3 Error: "PDF not Generated"

  • Check TCPDF folder presence

  • Set correct folder permissions

  • Re-upload missing template files

7.4 Error: "SMTP Connection Failed"

  • Use telnet to verify open SMTP port

  • Double-check credentials and encryption method

  • Switch to a basic SMTP server for testing

7.5 Error: "Module Won’t Activate"

  • Check /htdocs/custom/module_name folder permissions

  • Look for missing dependencies in module descriptor

  • Use logs to identify missing hooks or tables

8. Best Practices for Preventing Errors

  • Always back up before updates

  • Test custom modules in staging

  • Use compatible versions of PHP/MySQL

  • Keep Dolibarr core and modules updated

9. When to Ask for Community or Developer Support

  • When you’ve tested the issue on a clean install

  • When logs don’t reveal the issue

  • When your business operations are affected

10. Backup and Restore Tips Before Debugging

  • Use mysqldump for DB backup

  • Copy the full Dolibarr folder

  • Always restore in a test environment first

11. Hosting and Environment Considerations

Shared hosting often imposes PHP limits. VPS or dedicated hosting is more flexible for larger setups.

12. Using the Dolibarr Forum for Solutions

  • Search before posting

  • Include logs, versions, and reproduction steps

  • Engage respectfully with volunteers

13. How to Create a Bug Report for Developers

  • Use GitHub or Dolibarr Foundation channels

  • Follow bug report templates

  • Provide screenshots, logs, and exact steps

14. Useful Configuration Parameters

  • MAIN_LOGTOHTML for visible error logs

  • MAIN_DISABLE_ALL_MAILS to stop mail while testing

  • MAIN_HIDE_INACTIVETAB_ON_PRINT for cleaner print views

15. Tips for Stable Upgrades

  • Disable custom modules before upgrading

  • Follow upgrade scripts in order

  • Clear cache after upgrades

16. Managing Third-Party Modules and Compatibility

  • Always check module compatibility before install

  • Prefer modules from trusted sources (Dolistore)

  • Avoid editing core files directly

17. Real Business Scenarios and How They Were Solved

  • A logistics firm fixed PDF issues by correcting logo paths

  • A freelancer solved SMTP failure by changing mail provider

  • A retailer restored data after upgrade by rolling back from backup

18. Documenting Your Error Resolutions Internally

Maintain a shared document with:

  • Error message

  • Root cause

  • Resolution steps

  • Preventive actions

19. Resources and References

20. Conclusion

Errors in Dolibarr may seem intimidating at first, but with the right approach and tools, most can be resolved in minutes. By understanding common error types, practicing safe updates, and knowing when to seek help, you can maintain a stable and productive Dolibarr environment for your business.