Dolibarr error 500: finding the cause

A 500 error in Dolibarr shows nothing, and Dolibarr's own log does not contain it. Where to read the real message, how to understand it, and the four causes that come back almost every time.

You open a Dolibarr page and get a blank page, or your browser’s “Error 500” message. Nothing else: no message, no clue. That is intended. In production, Dolibarr and PHP hide error details, so as not to reveal anything to a malicious visitor.

The message does exist, though, and it almost always says exactly what is wrong. You just need to know where to read it, and we checked three things that waste a lot of time.

Three common beliefs, checked

We triggered two real fatal errors on a Dolibarr 24 test instance, then looked at where they showed up.

The browser receives nothing. HTTP 500 response, zero bytes. No point reloading the page or clearing the cache.
Dolibarr’s log does not contain the error. The dolibarr.log file does not even exist until the Logs module is enabled. And once enabled, it records the queries that precede the failure, but not the fatal error itself.
Setting $dolibarr_main_prod to 0 is not enough to display the error. This advice is everywhere. In the code, this setting only stops Dolibarr from hiding errors; it is the PHP configuration (display_errors) that decides whether to display them. In our test, with main_prod at 0 alone, the page stayed blank.

Where to read the real message

The error is written to the web server error log. Depending on your setup:

Debian or Ubuntu with Apache: /var/log/apache2/error.log.
Nginx with PHP-FPM: the Nginx error log, or the PHP-FPM one.
Docker, official image: docker compose logs web, PHP errors show up there directly.
Shared hosting: the logs or errors section of your control panel.

Reload the failing page, note the time, and look for PHP Fatal error at that time.

If you have no access to the logs at all, you can display the error on screen for one test: set $dolibarr_main_prod to 0 in conf/conf.php and enable display_errors in the PHP configuration. Reload, copy the message, then put both settings back: an error displayed in production hands paths and details to any visitor.

Reading the message

A fatal error message gives the error type, the file and the line. Three reflexes:

The file is in custom/: it is an external module. This is the most frequent cause, especially right after an upgrade.
Beware of the file named since version 20. When a module calls a method that no longer exists, the message points to a core file, core/class/doldeprecationhandler.class.php. The real culprit is written just before, after the word “From”. Here is what we got:
```
PHP Fatal error:  Call to undefined method 'methodeQuiNexistePlus'.
From /var/www/html/custom/panne/appel.php:6.
in /var/www/html/core/class/doldeprecationhandler.class.php on line 176
```
Dolibarr is not at fault here; custom/panne/appel.php, line 6, is.
The error type points to the cause, as the list below shows.

The four causes that come back almost every time

An external module incompatible with your version. Typical messages: Call to undefined method, Call to undefined function, Declaration of … must be compatible with …. Across the 280 real upgrades we tested, every fatal error came from the code of external modules. Fix: update the module, or disable it.
Memory. Message: Allowed memory size of … bytes exhausted. It mostly happens when generating a large PDF, an export or a long list. Fix: raise memory_limit in the PHP configuration, or reduce what the page has to load.
A missing PHP extension. Message: Call to undefined function on a function that does not belong to a module, for example an image or internationalisation function. It often happens after the host changes the PHP version. Fix: install the extension (intl, gd, zip, curl…).
A PHP version too recent for your code. Your host upgraded PHP, and an old module uses functions removed in PHP 8. Fix: update the module, or temporarily go back to the previous PHP version if the host allows it.

Disabling a module that blocks everything

If the faulty module prevents the modules screen from opening, you can disable it directly in the database. The query is given, with the precautions, in Dolibarr upgrade: checklist and upgrade path. Always check with a SELECT what the query will touch before deleting anything.

What Dolibarr’s log is still good for

Enabled from the Logs module, dolibarr.log (in the documents folder) does not record the fatal error, but it shows the last page opened and the last queries run just before. When the server log only reports a memory error, this is the file that tells you what Dolibarr was loading. Remember to disable it afterwards: it grows fast.

If you cannot find it

If the page fails with no usable message, or if the cause is in a module you cannot update, the €90 diagnosis is precisely about looking at your instance with you for one hour, then giving you in writing the cause and what the fix would cost.