Table of Contents

  1. Introduction

  2. Overview of Dolibarr Installation Requirements

  3. Issue 1: Blank Page After Launching Installer

  4. Issue 2: PHP Version Incompatibility

  5. Issue 3: Missing PHP Extensions

  6. Issue 4: File Permission Problems

  7. Issue 5: Database Connection Errors

  8. Issue 6: Incomplete Installation Wizard

  9. Issue 7: install.lock Not Created

  10. Issue 8: Conf.php File Not Writable

  11. Issue 9: Apache or Nginx Configuration Errors

  12. Issue 10: URL Rewrite and .htaccess Issues

  13. Issue 11: Timeouts During Installation

  14. Issue 12: Language Pack Installation Failures

  15. Issue 13: HTTPS or SSL Errors

  16. Issue 14: Problems with Shared Hosting Environments

  17. Issue 15: Reinstallation Loop

  18. Tools to Help Troubleshoot Installation Problems

  19. Best Practices to Prevent Installation Errors

  20. Conclusion


1. Introduction

Dolibarr is a robust and flexible ERP/CRM solution, but like any web-based application, its installation process can sometimes be hindered by server configuration, missing dependencies, or missteps during setup. This article presents a detailed analysis of the most common installation issues users face and provides actionable solutions.


2. Overview of Dolibarr Installation Requirements

Before beginning, ensure the server meets these requirements:

  • PHP 7.4 to 8.2

  • MySQL 5.7+ or MariaDB 10+

  • Apache/Nginx with mod_rewrite enabled

  • Required PHP extensions: pdo_mysql, gd, intl, zip, curl, json, mbstring, fileinfo

  • Writable directories: htdocs/conf/, documents/, and install/

Installing Dolibarr involves uploading the package, running the /install/ script, configuring the database, and finalizing setup.


3. Issue 1: Blank Page After Launching Installer

Symptoms:

  • Navigating to /install/ yields a white or blank screen.

Causes:

  • PHP error or fatal exception.

Solutions:

  • Enable error reporting in php.ini: display_errors = On

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

  • Ensure required PHP modules are installed

  • Use a different PHP version if the current one is buggy


4. Issue 2: PHP Version Incompatibility

Symptoms:

  • Deprecated warnings or function errors.

Causes:

  • Using an unsupported PHP version.

Solutions:

  • Use PHP 7.4 to 8.2, as per Dolibarr’s compatibility chart

  • Install proper version using your server’s package manager or tools like phpbrew or update-alternatives

  • Restart the web server after switching PHP version


5. Issue 3: Missing PHP Extensions

Symptoms:

  • Installer reports missing modules (e.g., intl, curl).

Causes:

  • Required PHP extensions not installed or not enabled.

Solutions:

  • Install extensions via package manager: sudo apt install php-intl php-curl php-gd php-mbstring

  • Check phpinfo() for confirmation

  • Restart Apache or Nginx after changes


6. Issue 4: File Permission Problems

Symptoms:

  • Configuration file not saved

  • Uploads not working

Causes:

  • Incorrect write permissions on required folders

Solutions:

  • Set ownership: chown -R www-data:www-data /var/www/html/dolibarr

  • Set permissions: chmod -R 755 /var/www/html/dolibarr

  • Ensure SELinux or AppArmor is not blocking write access


7. Issue 5: Database Connection Errors

Symptoms:

  • “Could not connect to database” during setup

Causes:

  • Wrong hostname, username, or password

  • MySQL service not running

  • User lacks CREATE privileges

Solutions:

  • Verify MySQL service with systemctl status mysql

  • Check credentials in Dolibarr installer

  • Grant privileges: GRANT ALL ON dolibarr.* TO 'user'@'localhost' IDENTIFIED BY 'password';


8. Issue 6: Incomplete Installation Wizard

Symptoms:

  • Setup gets stuck or reloads the same step

Causes:

  • PHP session or cache issue

  • Browser or server timeout

Solutions:

  • Clear browser cookies and restart the installation

  • Increase PHP timeout in php.ini: max_execution_time = 120

  • Use a different browser


9. Issue 7: install.lock Not Created

Symptoms:

  • Installer runs even after installation is complete

Causes:

  • Web server user lacks permission to create install.lock

Solutions:

  • Manually create /htdocs/install.lock

  • Set permissions: touch install.lock && chmod 644 install.lock

  • Confirm file is readable by the web server


10. Issue 8: Conf.php File Not Writable

Symptoms:

  • “conf.php cannot be written” error

Causes:

  • File not writable during setup

Solutions:

  • Set conf.php to writable: chmod 666 htdocs/conf/conf.php

  • After installation, set it back to read-only: chmod 444 conf.php


11. Issue 9: Apache or Nginx Configuration Errors

Symptoms:

  • 403 Forbidden or 404 Not Found errors

Causes:

  • Misconfigured virtual host or missing rewrite rules

Solutions:

  • Verify DocumentRoot and Directory settings in apache2.conf

  • Enable mod_rewrite: a2enmod rewrite

  • Add AllowOverride All to Apache config

  • For Nginx, ensure try_files $uri $uri/ /index.php?$query_string; is used


12. Issue 10: URL Rewrite and .htaccess Issues

Symptoms:

  • Friendly URLs not working

  • Menu links broken

Causes:

  • mod_rewrite not enabled or .htaccess ignored

Solutions:

  • Enable Apache’s mod_rewrite

  • Allow .htaccess overrides in Directory config

  • Test with: http://yourdomain/dolibarr/admin/index.php (direct URL)


13. Issue 11: Timeouts During Installation

Symptoms:

  • Installation process takes too long and fails

Causes:

  • Slow database

  • PHP execution timeout

Solutions:

  • Increase max_execution_time and memory_limit in php.ini

  • Monitor server load and optimize MySQL


14. Issue 12: Language Pack Installation Failures

Symptoms:

  • Language selection fails or errors appear

Causes:

  • Internet connectivity or file permission issues

Solutions:

  • Download packs manually from Dolibarr translation portal

  • Extract them into /htdocs/langs/

  • Verify correct folder names (e.g., fr_FR, en_US)


15. Issue 13: HTTPS or SSL Errors

Symptoms:

  • Browser warns about insecure connection

  • Some links not working under HTTPS

Causes:

  • SSL not properly configured

Solutions:

  • Install SSL certificate (Let’s Encrypt, etc.)

  • Update Dolibarr’s URL in conf.php to https://

  • Force HTTPS redirection in .htaccess


16. Issue 14: Problems with Shared Hosting Environments

Symptoms:

  • Limited PHP version or extensions

  • Permission errors

Causes:

  • Hosting provider restrictions

Solutions:

  • Choose a provider with support for custom PHP settings

  • Use .user.ini or .htaccess to set PHP values

  • Opt for a VPS or cloud server for full control


17. Issue 15: Reinstallation Loop

Symptoms:

  • Installation wizard restarts after completion

Causes:

  • Session lost or install.lock missing

Solutions:

  • Clear browser cookies

  • Verify install.lock exists and is readable

  • Double-check file system path in config


18. Tools to Help Troubleshoot Installation Problems

  • phpinfo() for PHP environment details

  • Apache/Nginx error logs

  • MySQL logs: /var/log/mysql/error.log

  • Browser developer tools (Console and Network tabs)


19. Best Practices to Prevent Installation Errors

  • Read Dolibarr’s installation guide carefully

  • Use staging servers for testing

  • Keep system packages updated

  • Monitor server resources

  • Document your installation steps and configs


20. Conclusion

Installing Dolibarr is a straightforward process when system requirements and permissions are met. However, overlooking small configurations can lead to frustrating errors. This guide provides comprehensive solutions to the most common installation issues so you can move from setup to productivity without delays. Proper planning, permissions, and system compatibility are the pillars of a successful deployment.