Table of Contents

  1. Introduction

  2. Why Errors Happen After an Update

  3. Best Practices to Avoid Update Failures

  4. Error 500: Internal Server Error

  5. Blank Screen After Login

  6. Module Not Displayed or Missing

  7. Broken PDF Generation

  8. Language or Translation Issues

  9. Theme/Layout Distortion or Missing Icons

  10. Permissions Issues Post-Upgrade

  11. Database Migration Conflicts

  12. Conf.php Misconfigurations

  13. Apache/Nginx Rewrite and Access Errors

  14. Deprecated Functions in Custom Modules

  15. External Modules Incompatibility

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

  17. Step-by-Step Debugging Strategy

  18. Rolling Back to a Previous Working Version

  19. Reporting Bugs to the Dolibarr Community

  20. Conclusion

1. Introduction

Updating Dolibarr can be a smooth process when planned well, but in many cases, post-update issues disrupt workflows. Whether you’re dealing with blank screens, access errors, or broken PDFs, this guide helps you resolve common problems and stabilize your ERP/CRM instance.

2. Why Errors Happen After an Update

Typical causes include:

  • Incomplete file replacement

  • Old modules/themes incompatible with new structure

  • Database upgrade scripts not running fully

  • Misconfigured server environment (PHP version, extensions)

  • Cached settings causing UI issues

Understanding the root cause helps resolve issues faster.

3. Best Practices to Avoid Update Failures

Before updating:

  • Backup everything (database and file system)

  • Update on a staging server first

  • Disable non-essential modules

  • Check for known issues on GitHub or forums

  • Read the changelog and release notes

Never update directly on a production instance without testing.

4. Error 500: Internal Server Error

This is a general error. Likely causes:

  • Incorrect file permissions (chmod)

  • Syntax errors in customized PHP files

  • Incompatible third-party modules

Fix:

  • Check web server error logs (/var/log/apache2/error.log)

  • Set file permissions to 644 and folders to 755

  • Temporarily disable all custom modules and retry

5. Blank Screen After Login

Common causes:

  • PHP error suppressed (display_errors = Off)

  • Corrupted session files or cache

Fix:

  • Enable error reporting in conf.php

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

  • Clear browser cache and Dolibarr’s cache folder /documents/temp

6. Module Not Displayed or Missing

Symptoms:

  • A previously active module is now gone

Fix:

  • Go to Setup > Modules and re-enable it

  • If custom, verify it’s located in /custom/module/

  • Check compatibility with the current Dolibarr version

7. Broken PDF Generation

Symptoms:

  • PDF outputs are blank or malformed

Fix:

  • Check for missing TCPDF libraries

  • Ensure /documents/ has proper write permissions

  • Confirm language files (langs/) are not corrupted

Also inspect the custom template logic for deprecated TCPDF functions.

8. Language or Translation Issues

Symptoms:

  • Interface not translated, or gibberish shown

Fix:

  • Check for UTF-8 encoding issues

  • Re-save language files in proper encoding

  • Verify translations folder exists at /htdocs/langs/

  • Use Setup > Translation > Rebuild Dictionary

9. Theme/Layout Distortion or Missing Icons

Symptoms:

  • Layout appears broken after update

  • Icons are missing

Fix:

  • Clear browser cache

  • Revert to a supported theme like Oblyon

  • Check CSS/JS file loading paths in browser dev tools

  • Ensure no custom CSS files were lost or corrupted

10. Permissions Issues Post-Upgrade

Symptoms:

  • Users see "Access Denied" on modules they previously accessed

Fix:

  • Reset user permissions in Users & Groups > Permissions

  • Check user group inheritance

  • Compare old and new module permission structure

11. Database Migration Conflicts

Symptoms:

  • Error loading pages referencing missing tables or columns

Fix:

  • Rerun the update wizard at /install/

  • Compare schema using tools like phpMyAdmin

  • Manually apply missing changes from install/mysql/upgrade scripts

12. Conf.php Misconfigurations

Symptoms:

  • Dolibarr won’t load at all

Fix:

  • Check $dolibarr_main_url_root, $dolibarr_main_document_root and DB connection lines

  • Ensure proper quotes and no trailing spaces

13. Apache/Nginx Rewrite and Access Errors

Symptoms:

  • Error 404 or 403 when accessing modules

Fix:

  • Ensure .htaccess is intact (Apache)

  • Confirm mod_rewrite is enabled

  • For Nginx, update rewrite rules accordingly

14. Deprecated Functions in Custom Modules

Symptoms:

  • Logs show warnings or crashes from outdated code

Fix:

  • Compare your module’s code with updated core logic

  • Replace deprecated function calls

  • Read migration notes in Dolibarr’s GitHub releases

15. External Modules Incompatibility

Symptoms:

  • Modules from Dolistore no longer function

Fix:

  • Check vendor site for an updated version

  • Contact the module author for support

  • Disable the module temporarily

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

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

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

  • PHP: /var/log/php_errors.log

  • Dolibarr: /documents/admin/system.log (if enabled)

Always read from the bottom up to find the latest events.

17. Step-by-Step Debugging Strategy

  1. Turn on error reporting in conf.php

  2. Isolate the problem (which module, user, file?)

  3. Check web server and Dolibarr logs

  4. Disable non-core modules

  5. Revert to a backup if needed

Don’t panic—most issues can be resolved with methodical steps.

18. Rolling Back to a Previous Working Version

If everything fails:

  • Restore your last backup of both database and files

  • Downgrade only if absolutely necessary

  • Document what caused the failed upgrade

Use rollback only when you’re stuck, and plan for a reattempt after debugging.

19. Reporting Bugs to the Dolibarr Community

If you find a genuine bug:

  • Search the Dolibarr GitHub Issues

  • Submit a new issue with:

    • Your version

    • Steps to reproduce

    • Logs or screenshots

Clear reporting increases your chances of getting help fast.

20. Conclusion

Post-update errors are common but manageable. With clear logging, backups, and a systematic debugging approach, most issues can be resolved quickly. Use staging environments, keep third-party modules current, and contribute fixes to help the community grow stronger.