Common causes for SSL, HTTPS, and certificate errors in Matomo

On-Premise

SSL and HTTPS issues in Matomo typically appear as cURL errors, archiving failures, plugin download problems, or redirect loops. In most cases, these issues are caused by missing, outdated, or misconfigured SSL certificates on the server.

This guide describes common SSL and HTTPS configuration issues with recommended steps to resolve the errors.

Basic SSL connectivity checks

Before troubleshooting a specific error, verify that the Matomo server can establish outbound HTTPS connections. You can do this by running the following commands directly on the server.

Example (Linux / macOS)

ping www.googleapis.com
curl -v "https://www.googleapis.com/pagespeedonline/v5/runPagespeed"

Example (Windows / PowerShell)

curl -v "https://www.googleapis.com/pagespeedonline/v5/runPagespeed"
  1. If these commands fail, the issue is likely related to SSL configuration, certificate trust, or network access. Update the system’s trusted CA certificates using the recommended method for your operating system.
  2. To verify whether your SSL certificate is valid and correctly configured, you can test it using an external tool such as SSL Server Test.
  3. In some environments, firewall rules, proxy settings, or network policies may restrict outbound HTTPS connections. If other steps do not resolve the issue, verify these settings.

Common SSL and HTTPS issues

1. PHP does not support HTTPS (OpenSSL not enabled)

When PHP is not configured with OpenSSL support, it cannot handle HTTPS connections and prevents Matomo from making secure requests. If you encounter the following errors, it means that PHP was built without OpenSSL support or the OpenSSL extension is disabled:

  • Unable to find the wrapper "https"
  • HTTPS requests fail immediately without connecting.

Solution

  1. Install or enable the PHP OpenSSL extension. For example:
    • FreeBSD: install php_openssl
    • Windows: uncomment extension=php_openssl in php.ini
  2. Restart the web server after enabling it.

2. SSL certificate is not trusted (missing or outdated CA)

This issue occurs when your Matomo server cannot verify the SSL certificate presented by another service. In many cases, it happens when Matomo attempts to access its own URL over HTTPS while running background tasks such as report archiving.

Although the connection uses HTTPS, the server does not recognise or trust the certificate authority that issued the certificate, causing the request to fail. You may see one or more of the following:

  • curl_exec: SSL certificate problem: unable to get local issuer certificate
  • Auto archiving fails when accessing Matomo over HTTPS.
  • Requests to external HTTPS services fail, such as plugin updates or API calls.

Common scenario: archiving over HTTPS

This error can occur during automatic archiving when the core:archive command tries to access your Matomo URL over HTTPS, but the SSL certificate cannot be validated by the server.

If possible, fix the SSL certificate configuration for the Matomo URL. This ensures that the archiver and all HTTPS requests can run securely and without workarounds. It involves updating your system’s CA certificates or configuring PHP to use a valid CA bundle.

  1. Download the latest cacert.pem.
  2. Configure PHP to use it:
curl.cainfo="/path/to/cacert.pem"

Temporary workaround for archiving only

If you cannot immediately fix the SSL certificate issue, you can instruct the archiving command to ignore SSL certificate validation. This workaround allows archiving to proceed, but it is not recommended as a permanent solution.

Add the following flag to your archiving cron job: --accept-invalid-ssl-certificate. For example:

/usr/bin/php /path/to/matomo/console core:archive --accept-invalid-ssl-certificate --url=https://example.org/matomo/ > /dev/null

3. SSL interception by firewalls or proxy servers

This happens when a firewall, proxy, or security appliance intercepts HTTPS traffic and re-encrypts it using its own SSL certificate. Although the connection is still encrypted, Matomo cannot verify the certificate because it is not issued by a trusted public certificate authority. When the following errors appear, a firewall or proxy is intercepting HTTPS traffic and re-signing certificates using a custom CA:

  • Peer’s Certificate issuer is not recognized
  • Errors when connecting to plugins.matomo.org, such as during plugin installation or updates.

Solution

Provide Matomo with a custom CA certificate that trusts the proxy.

  1. Upload your custom cacert.pem
  2. Add to config.ini.php and ensure the file is readable by the web server.
custom_cacert_pem = "/path/to/cacert.pem"

4. HTTPS redirect loops or broken reports

The issue occurs when HTTPS is enabled but the web server does not correctly pass the secure connection information to PHP. Matomo then cannot reliably detect whether requests are already using HTTPS, which can result in repeated redirects or broken report generation.

If you encounter too many redirect errors when accessing Matomo or CSV or PDF reports and graphs are failing to load over HTTPS, then the web server does not correctly signal HTTPS to PHP.

Solution

  1. Set assume_secure_protocol = 1, or
  2. Configure the web server to pass the HTTPS environment variable. For example,

lighttpd

setenv.add-environment = ( "HTTPS" => "on" )

nginx

fastcgi_param HTTPS on;

Next steps

Most SSL-related errors in Matomo fall into one of the categories described above, even if the error message differs. Once SSL and HTTPS are configured correctly, Matomo should be able to communicate reliably with external services and run background processes without errors.

If the problem persists after following the steps in this guide, collect the following information before contacting Matomo support:

  • Operating system.
  • Web server (for example, Apache or Nginx).
  • PHP version.
  • Relevant PHP or SSL configuration details.

Providing these details helps diagnose SSL issues quickly and accurately.