Dolibarr is a robust and widely used open-source ERP and CRM system. It’s favored for its flexibility, ease of use, and ability to be customized to fit different business needs. However, like any complex software, users can occasionally face issues—one of the most alarming being when Dolibarr suddenly stops working or refuses to open at all.

Whether your Dolibarr is hosted locally or on a remote server, a blank page or error message can mean a variety of things. In this detailed guide, we will explore the most frequent causes behind this issue and provide practical, step-by-step solutions to help you get your system back online.

Table of Contents

  1. Initial Assessment: Is Dolibarr Really Down?

  2. Web Server and Service Status Check

  3. White Screen of Death (WSOD)

  4. PHP Errors and Misconfigurations

  5. Database Connection Failures

  6. Corrupted or Missing Files

  7. Permissions and Ownership Problems

  8. Misconfigured conf.php File

  9. Issues Following a Recent Update or Migration

  10. Browser-Related or Cache Issues

  11. Error Logs: Your Best Friend

  12. Using Developer Mode to Debug

  13. Recovery Strategies

  14. Preventive Measures

  15. Final Thoughts and Recommendations

1. Initial Assessment: Is Dolibarr Really Down?

Before diving into technical troubleshooting, start with a quick assessment:

  • Does the page load at all? Or is it completely blank?

  • Do you receive a specific HTTP error (e.g., 403, 404, 500)?

  • Can you access the database directly?

  • Are you the only user experiencing the issue, or is it affecting everyone?

Understanding the context helps narrow down the problem. A global outage points to server-side issues, while user-specific issues may be local.

2. Web Server and Service Status Check

If Dolibarr is self-hosted, your first step is to check if the web server (Apache, Nginx, etc.) and related services are running.

sudo systemctl status apache2
sudo systemctl status nginx
sudo systemctl status mysql

If any of these services are inactive or failed, restart them:

sudo systemctl restart apache2
sudo systemctl restart mysql

Make sure your server has not run out of memory or disk space, which can cause these services to crash.

3. White Screen of Death (WSOD)

A blank white screen with no error messages is often referred to as the White Screen of Death. In PHP-based applications like Dolibarr, it usually signals a fatal error in the code.

To uncover the root cause:

  • Enable error reporting in conf.php:

$dolibarr_main_prod = 0;

  • Check web server logs and PHP logs

Blank screens almost always indicate missing includes, syntax errors, or a failed upgrade.

4. PHP Errors and Misconfigurations

Many Dolibarr problems arise from PHP issues, especially after updates.

Common PHP-related problems include:

  • Incompatible PHP versions

  • Disabled extensions (like pdo_mysql, gd, json)

  • Memory limits that are too low

Fixes:

  • Verify PHP version compatibility with your Dolibarr release

  • Use php -m to list installed extensions

  • Modify php.ini to increase memory:

memory_limit = 512M

Restart the server after making changes.

5. Database Connection Failures

Dolibarr relies heavily on its MySQL or PostgreSQL database. If it cannot connect, the application won't load.

Symptoms:

  • Blank screen with no error

  • Message like "Connection refused" or "Access denied"

What to check:

  • conf.php contains correct DB credentials

  • MySQL server is running

  • The database user has the right privileges

Try connecting manually via the command line:

mysql -u dolibarruser -p dolibarrdb

6. Corrupted or Missing Files

Updates, server crashes, or file transfer interruptions can corrupt files.

To check:

  • Compare your current Dolibarr files to a clean copy

  • Look for partially uploaded files or incorrect file sizes

Solution:

  • Re-upload a clean copy of Dolibarr (except conf.php and /documents)

  • Check .htaccess and module folders

7. Permissions and Ownership Problems

Incorrect file permissions are a frequent cause of issues, especially after a migration or manual update.

Recommended Permissions:

chown -R www-data:www-data /var/www/dolibarr
find /var/www/dolibarr -type f -exec chmod 644 {} \;
find /var/www/dolibarr -type d -exec chmod 755 {} \;

Adjust the user/group based on your server setup.

8. Misconfigured conf.php File

The conf.php file in /htdocs/conf/ is critical. If its content is modified or deleted, Dolibarr won’t load.

Check for:

  • Correct database credentials

  • Proper paths (especially if you’ve moved servers)

  • Valid PHP syntax (missing semicolons, etc.)

Always edit this file using a code editor, not a word processor.

9. Issues Following a Recent Update or Migration

Many Dolibarr failures occur right after a version upgrade or a server migration.

Causes:

  • Incomplete file uploads

  • Skipped database upgrade steps

  • Module incompatibilities

Fix:

  • Go to /install/ and complete the upgrade wizard

  • Re-run SQL upgrade scripts manually if needed

  • Move incompatible modules out of the custom/ folder

10. Browser-Related or Cache Issues

Sometimes, Dolibarr may be working fine, but your browser shows a cached error.

Solutions:

  • Clear browser cache

  • Use incognito mode

  • Try accessing from another browser or device

You can also clear the server cache if you've implemented any reverse proxy or caching layer.

11. Error Logs: Your Best Friend

Error logs often contain the exact cause of the problem. Check:

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

  • PHP logs: Depending on your php.ini config

  • Dolibarr log: /documents/dolibarr.log

Search for recent entries with "Fatal", "Error", or "Warning" messages.

12. Using Developer Mode to Debug

Setting $dolibarr_main_prod = 0; in your conf.php file will display PHP errors directly in the browser, aiding debugging.

Use this only temporarily in a secure environment, not on a public-facing server.

You can also install debugging tools like Xdebug to step through the code if necessary.

13. Recovery Strategies

If standard fixes don’t work, consider these:

  • Restore a recent backup: Most reliable option if you have a good snapshot

  • Set up a fresh Dolibarr installation and migrate the database to it

  • Hire a professional if the issue is complex and business-critical

Having a downtime response plan will help you act quickly and minimize impact.

14. Preventive Measures

Prevent future incidents by:

  • Regularly backing up files and database

  • Using version control for custom modules

  • Testing updates in a staging environment first

  • Monitoring disk space and performance

  • Restricting server access to trusted personnel

These habits go a long way in maintaining a healthy Dolibarr system.

15. Final Thoughts and Recommendations

When Dolibarr stops opening, it can feel like your entire business system is frozen. But most causes are identifiable and fixable with a structured troubleshooting process.

Start with the basics—server and service checks—then move on to configuration files, error logs, and PHP settings. Keep your installation clean, modular, and well-documented.

And most importantly, prepare for the unexpected. With the right preventive strategy, you’ll ensure Dolibarr stays up and running when you need it most.