Table of Contents

  1. Introduction

  2. Why Upgrades Can Cause Errors in Dolibarr

  3. Preparing for an Upgrade: Best Practices

  4. Common Upgrade Error Categories

  5. Case Study 1: Database Schema Mismatch

  6. Case Study 2: PHP Version Incompatibility

  7. Case Study 3: Missing install.lock File

  8. Case Study 4: Module Compatibility Issues

  9. Case Study 5: File Permission Errors

  10. Case Study 6: Blank or Broken UI After Upgrade

  11. Case Study 7: Language File Errors

  12. Case Study 8: Cron Jobs and Scheduled Tasks Failing

  13. Analyzing logs: Where to Look and What to Watch

  14. Tools and Scripts to Aid in Troubleshooting

  15. Rolling Back Safely from a Failed Upgrade

  16. Lessons Learned and Preventive Strategies

  17. Community and Professional Support Resources

  18. Conclusion

1. Introduction

Dolibarr ERP/CRM is widely adopted for its flexibility and modular design. However, like any complex system, upgrades—especially major ones—can lead to unexpected issues. Understanding, diagnosing, and resolving these errors quickly is crucial for business continuity. This article explores real-world upgrade error scenarios, their root causes, and structured solutions.

2. Why Upgrades Can Cause Errors in Dolibarr

Each new version introduces changes in:

  • Database schemas

  • PHP functions and compatibility

  • Internal APIs and class structures

  • UI templates and rendering logic

  • Module interfaces and configurations

If these changes aren’t matched with proper preparation and testing, errors are almost inevitable.

3. Preparing for an Upgrade: Best Practices

Before upgrading:

  • Backup your database and file system.

  • Test the upgrade in a staging environment.

  • Check your PHP version compatibility.

  • Verify third-party module compatibility.

  • Confirm the presence of install.lock.

  • Document customizations for reimplementation.

A checklist-driven approach reduces risk dramatically.

4. Common Upgrade Error Categories

  • Database errors: schema mismatch, missing columns

  • Fatal PHP errors: class/function not found

  • UI rendering issues: broken layouts, missing templates

  • Language errors: missing translations

  • Access issues: permission errors after file changes

  • Module malfunctions: custom code failing after core change

Each category may manifest with vague symptoms like blank screens, 500 errors, or UI glitches.

5. Case Study 1: Database Schema Mismatch

Symptom:

“Unknown column 'ref_ext' in 'field list'” when viewing invoices.

Root Cause:

Skipped or failed execution of a database migration step.

Resolution:

  • Check /install/ directory for the upgrade wizard.

  • Review the llx_const table for version tracking.

  • Re-run the upgrade from /install/

  • Manually compare llx_facture structure using the /install/mysql/ files

6. Case Study 2: PHP Version Incompatibility

Symptom:

White screen or "Deprecated function" error.

Root Cause:

Dolibarr version requires newer or older PHP version than current.

Resolution:

  • Check Dolibarr’s official PHP compatibility matrix

  • Update PHP if too old, or downgrade if version is too new

  • Ensure necessary PHP extensions (pdo, gd, intl) are installed

7. Case Study 3: Missing install.lock File

Symptom:

Dolibarr shows installation wizard instead of login.

Root Cause:

The install.lock file was deleted or not recreated.

Resolution:

  • Create an empty file named install.lock in the root directory

  • Set correct permissions (644)

  • Lock /install/ directory with .htaccess as a secondary measure

8. Case Study 4: Module Compatibility Issues

Symptom:

Custom modules no longer load or throw exceptions.

Root Cause:

Changes in core hooks, class structures, or API signatures.

Resolution:

  • Check module compatibility with your Dolibarr version

  • Update the module if a newer version exists

  • Disable incompatible modules temporarily

  • Examine error logs to pinpoint outdated functions

9. Case Study 5: File Permission Errors

Symptom:

“Permission denied” errors during file uploads or PDF generation.

Root Cause:

File system permissions reset or misconfigured after upgrade.

Resolution:

  • Set htdocs and documents folders to writable by the web user

  • Use chmod -R 755 and chown -R www-data:www-data

  • Confirm conf.php is readable

10. Case Study 6: Blank or Broken UI After Upgrade

Symptom:

Login screen loads, but after login the interface is blank.

Root Cause:

Theme or template incompatibility.

Resolution:

  • Switch to a default theme (Eldy) from the database directly

  • Clear cache from documents/temp/

  • Disable custom CSS or JavaScript

11. Case Study 7: Language File Errors

Symptom:

Labels missing or untranslated despite language settings.

Root Cause:

Outdated or missing language files for new features.

Resolution:

  • Run the language cache reset via admin/tools.php?action=clear_langcache

  • Download latest language pack from Dolibarr’s translation portal

  • Manually update files in /langs/

12. Case Study 8: Cron Jobs and Scheduled Tasks Failing

Symptom:

Invoices, reports, or tasks fail to execute as scheduled.

Root Cause:

Cron URLs changed or cron_run_jobs.php path shifted.

Resolution:

  • Update cron job to reflect new Dolibarr version path

  • Verify that cron_run_jobs.php is executable

  • Check logs in documents/admin/cronjobs.log

13. Analyzing logs: Where to Look and What to Watch

Key locations:

  • htdocs/conf/conf.php → database and debug settings

  • htdocs/logs/ (if enabled)

  • Apache/Nginx error logs

  • documents/admin/system.log

  • Browser console for JS errors

Enable $dolibarr_main_prod = 0; in conf.php for verbose error output (for debugging only).

14. Tools and Scripts to Aid in Troubleshooting

  • dolibarr_dev_tools GitHub repository

  • Admin tools: Database integrity checker

  • SQL diff tools (e.g., MySQL Workbench)

  • File comparison: diff, Meld, Beyond Compare

15. Rolling Back Safely from a Failed Upgrade

  • Restore from your pre-upgrade database backup

  • Revert file system from the zipped Dolibarr directory

  • Disable all non-core modules

  • Use version control for config and module files

Always test rollback strategy in staging before applying to production.

16. Lessons Learned and Preventive Strategies

  • Never upgrade directly on production without testing

  • Automate backups and restore processes

  • Maintain documentation of installed modules and their versions

  • Read Dolibarr changelogs and forum threads before upgrading

  • Subscribe to Dolibarr release updates for early warnings

17. Community and Professional Support Resources

18. Conclusion

Dolibarr upgrades can be challenging, especially when environments are heavily customized. However, with proper planning, knowledge of common pitfalls, and structured troubleshooting, most errors can be resolved quickly and safely. This guide equips you with practical case-based insights and actionable steps to ensure that your next upgrade is smooth and stress-free.