The openssl extension is required for SSL/TLS protection

The openssl extension is required for SSL/TLS protection

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

The openssl extension is required for SSL/TLS protection

When executing a fresh Flarum installation via composer create-project flarum/flarum . --stability=beta, you might encounter a RuntimeException that halts progress immediately. The error message is explicit: "The openssl extension is required for SSL/TLS protection but is not available." It offers a fallback option to disable TLS, but this introduces significant security risks for any public-facing application.

This error typically manifests when the PHP interpreter cannot locate or load the openssl module, even if you believe you have configured your environment correctly. The core issue usually stems from how modern PHP distributions handle extensions versus legacy configurations.

Why the Extension Matters

Modern PHP distributions (such as those used in Flarum) often default to compiling OpenSSL support dynamically rather than statically linking it into the core binary. This design choice allows for easier updates and dependency management but requires explicit configuration to load the extension at runtime. If this module is missing, any attempt to establish secure connections via HTTPS will fail, preventing the application from binding to an SSL-enabled port.

Verifying Your Configuration

The most common misconception involves editing php.ini. Many developers assume that adding extension=php_openssl.dll (on Windows) or extension=openssl (on Linux/macOS) is sufficient. While this line tells PHP which shared object file to load, the path matters significantly.

On Windows systems, if you have added the correct line to your php.ini, ensure that the corresponding .dll file exists in your PHP installation directory and that the extension_dir directive points to that same folder. If the file is missing or the path is incorrect, PHP will silently ignore the configuration line without throwing an immediate error during initialization.

On Linux and macOS systems, the situation can be trickier. Modern distributions like Alpine Linux often use statically linked OpenSSL libraries. In these environments, you might need to install the PHP-specific package rather than relying on system libraries alone. For example:

# Debian/Ubuntu based systems
sudo apt-get install php-openssl

# RHEL/CentOS based systems
sudo dnf install php-openssl

After installing or configuring the extension, you must restart your web server or PHP-FPM service to apply changes. Simply saving the php.ini file is insufficient if the service remains running.

The Disable-TLS Warning

The error message suggests setting the 'disable-tls' option to true as an alternative. This flag tells Flarum to skip SSL validation entirely, allowing the application to run over HTTP or ignoring certificate requirements. While this might seem like a quick fix for local development, it should never be used in production environments. Running without TLS exposes sensitive user data, including session tokens and form submissions, to network eavesdropping.

If you are developing locally and require HTTPS (for example, to test browser security headers or cookie policies), consider using a reverse proxy like Nginx or Traefik that handles SSL termination. This allows your PHP backend to communicate over HTTP internally while presenting valid certificates to external clients.

Troubleshooting Persistent Issues

If you have verified the extension=openssl line in your configuration and restarted your server, yet the error persists, check for multiple php.ini files being loaded. Some environments use a different configuration file for CLI versus FPM, or specific virtual host configurations may override global settings. Use the following command to identify which configuration file is actually active:

php -i | grep "Configuration File"

Ensure your modifications exist in that specific file. Additionally, verify that no other modules are conflicting with the OpenSSL extension by checking for error logs generated by PHP-FPM or Nginx/Apache.

Next Steps

Once the extension is properly loaded and verified via php -m, retry your Composer command. The application should proceed to install dependencies and initialize the database structure without triggering the runtime exception. Remember that while disabling TLS offers a workaround, maintaining proper SSL/TLS support is essential for any web application handling user credentials or personal data.

Our network