All visitors have the same IP address and Provider. How do I track individual IPs?

If you are seeing that all your visitors are correctly tracked in Matomo (Piwik) but that they all have the same IP address, read on. In your ‘Visitor Log’ report, if all your visitors have the same IP address or the same Provider, this FAQ will provide a solution.

Why do I see the same IP everywhere?
In most cases this IP address (that is set to all visitors) is either the IP of the Matomo server itself or maybe the IP of a proxy server or a firewall between your website’s visitors and the server hosting your website. Sometimes the IP address will be set as 0.0.0.0.

How do I fix this issue?
1. Your Matomo server may actually be hosted behind a proxy. To configure Matomo to track IP address correctly when using a Proxy server, read this FAQ to configure Matomo to read the correct IP address. As explained in this FAQ you may add lines in your Matomo config file to tell Matomo where to read the IP address.
2. Are you using the Tracking API? You may also experience this problem when you are using one of the Tracking API clients to record visits and actions. You may use the method setIP() to overwrite the IP address manually. See the reference.

What about is my visitors really have the same IP address, what should I do?

Sometimes people who view your website do actually have the same IP address. This is the case when:

  • users all belong to the same internal network, and are viewing your intranet website
  • users use a VPN and all appear as coming from the same IP address.

In that case we recommend to look at the FAQ How do I track people on my Intranet?.

Matomo tracks far fewer visits than other web analytics tools, but tracks the same number of pageviews.

If you use other web analytics tools on your website, in some rare cases you may find that Matomo (Piwik) tracks far fewer visits than other tools.

While there are explanations for small differences, sometimes Matomo will track fewer visits but about the same number of pageviews (actions). When this happens, it shows that the algorithm attributing Visits to particular pageviews is not working as expected.

If your website visitors are visiting from one IP address (eg. they connect from the same offices), then Matomo may mistakenly believe all actions by this IP address are the same. In this case you can set a setting in the config file, make a change to your config file as explained in this FAQ.

The Real Time Visitors World Map is not showing data.

The Real Time Visitor Map is a great tool for Matomo (Piwik) users. It lists, in real-time, all visitors to the website and puts them on the map according to their country and locations (based on country, region, city and/or latitude and longitude).

If the Real Time Map is for you not showing any data, please check the following items:

  • Make sure you have enabled Geo-location with the City database in your Matomo. Geo-location will enable Matomo to try and fetch the following information for each visitor: country, region, city, latitude and longitude. After enabling City Geo-location (for example using the Geoip php or Geoip PECL options), most of your visitors will be geo located and should be displayed on the map!
  • Do you get Javascript errors on the Map? This may occur when your server is not configured to properly serve SVG files. Matomo Maps stores the countries boundaries to draw the map, in SVG files.
    • If you are using Apache webserver, create a .htaccess file, in the piwik/ directory, with the following content:
AddType image/svg+xml svg svgz
AddEncoding gzip svgz
  • If you are using Nginx webserver, in your mime.types file (example mime.types), add the following:
  image/svg+xml svg svgz;

Matomo doesn’t track any visits and pages, and shows « There is no data for this report » in all reports.

There are several possible reasons why Matomo (Piwik) is not tracking your visits properly:

  • Incorrect Matomo tracking code Please check that you can find the Matomo javascript code on your website pages that you wish to track. Sometimes, when you copy paste the javascript code in other softwares, like Word or FrontPage, they may add extra spaces or characters. Make sure the code looks like this example (and that it mentions the right URL of your Matomo installation). In some cases, when you install Matomo on your local test server, the javascript code might contain « localhost » or « 127.0.0.1 ». When you deploy Matomo in production, you have to edit the Javascript code so that it points to your website URL, eg. « http://example.org/piwik/ ». Also, each Matomo tracking code contains the idsite of your website registered in Matomo. If you only registered one website in Matomo, the idsite found in your Javascript code should be « 1 ».
  • Make sure you are viewing reports for the correct website and date in Matomo In Matomo, make sure you selected the right website in the website selector. Also, try to look at reports for « today » by changing the date in the date picker. Please wait at least 10 seconds after generating visits on your website: by default Matomo will only process reports every 10 seconds when « today » is selected.
  • Browser addons blocking the Matomo Tracking Javascript (NoScript, DoNotTrack, etc.) If you use browsers addons such as Adblock, Adblock plus, NoScript, Ghostery or others, the Matomo Javascript code is not executed in your browser. Try to use a different browser that does not have these extensions, or disable these browser extensions and try again.
  • Matomo by default supports DoNotTrack: please check you haven’t enabled DoNotTrack in your browser options.
  • Archiving triggered from the browser must be enabled, if it is disabled the Cron script must be configured properly
    In Administration > General Settings, ‘Allow Matomo archiving to trigger when reports are viewed from the browser’ must be set to ‘Yes’. If it is set to ‘No’, you must configure the cron script to automatically archive your web analytics reports, or Matomo will show ‘No Data’. More information about auto archiving.
  • Third party Matomo plugins It is possible that some Third party Matomo plugins could cause problems when tracking your visitors. Please try to disable all the third party plugins you are using to see if it fixes the issue.
  • Do you have logs registered in your Matomo database? If your Matomo tracking code is properly installed, Matomo would record visits in your database. To check if you have logs in your database, go to Matomo > Visitors > Visits log, and select « today » in the calendar. If you see recent visitor information, it means that the visitor tracking is working, but maybe there is a problem with reports archiving. Note: you can also check if logs are recorded correctly by looking at the table « matomo_log_visit » (using phpMyAdmin for example) and see if there are visits recorded. Alternatively, you can enable the plugin « DBStats », and then go to the « Database usage » tab in your Matomo administration area, and check if the table matomo_log_visit has any rows.
  • Testing Matomo with disabled Javascript By default, Matomo only tracks visitors with javascript enabled. When you are testing that Matomo tracks visits properly make sure you have javascript enabled. If you need help with javascript tracking check out docs/javascript-tracking. If you need to use a tracking method which doesn’t involve javascript have a look at docs/tracking-api.
  • Matomo displays a red cross (on IE) or a broken image icon on your tracked pages, instead of the 1*1 transparent Pixel Check out this FAQ answer.
  • Access to piwik.php fails If your host uses mod_security to block requests containing URLs (eg. hosts like HostGator, The Planet), check out the Matomo and mod_security FAQ. If you use HTTP Authentication (Basic or Digest) on your Matomo files, you should exclude piwik.php and piwik.js from this authentication, or visitors on your website would be prompted with the authentication popup.
  • Tracking https (SSL) pages If you install the Matomo Javascript Tracking tag on https:// pages, then the tracking requests will be sent to Matomo via https. This means that the server you installed Matomo on must be able to handle these https requests, or no data will be tracked. See also Matomo and SSL tracking and checking that Matomo SSL Server is correctly configured.
  • Local copy of piwik.js outdated Some users make a local copy of piwik.js on a different server than their Matomo installation. This is not officially supported and causes issues when the piwik.js bundled with Matomo is updated and not compatible with the previous version (for example, this is the case in Matomo 0.5.5). Please check that your Matomo JS tracking code is exactly the one given in the Matomo admin screen.
  • Using Matomo latest version If you are still seeing « No data », please make sure you are using the latest version of Matomo (if not, update now).
  • Check your webserver error logs If all else fails, it is possible that there is a server misconfiguration preventing Matomo from tracking your visits or processing reports. Often, there will be an error in the webserver error logs (apache logs, IIS logs, nginx logs, etc.). Please check that your PHP is configured to log errors: (php.ini should contain log_errors = On and error_log = /path/to/log). The messages in the webserver error log will help you find the source of the problem, for example search for the error message on this website.
  • Troubleshooting when a tracking request is sent correctly but data is not visible in ‘Visits log’ When you can see in the Browser Developer Tools > Network panel that your tracking requests are correctly sent to the Matomo Tracking API (matomo.php?), but your data is not tracked then you can quite easily debug the tracker. Follow the steps in Debugging the Tracker. Tracking requests will then output the tracking log messages in readable english, and it will clearly say any issue or reason why the request is not being tracked.

How do I find and copy the system check in Matomo On-Premise?

If you are using Matomo for WordPress please click here. If you are on the Matomo Cloud, please let our support know that you are using our Cloud hosted service. In this case you won’t need to send us a system report.

If you have a problem with your Matomo we may ask you to send us your system check (or system report) so we can better understand and replicate the problem. To find the system check please follow these steps:

  • Log in to your Matomo as a super user
  • Click on the cog icon in the top right navigation to go to the administration area.
  • In the left menu click on the « System Check » link which you find under the « Diagnostics » section
  • You will now see a button « Copy System Check » and « Download System Check ».
  • The copy button will copy the entire system check into your clipboard. Use this if you want to paste the content for example in our Matomo GitHub issue tracker.
  • The download button will trigger the download of a text file that contains the system report so you can easily attach it for example to an email.
  • The copied content of the system check should be anonymised and not contain private or sensitive information so it can be easily shared.

Please note that this feature is only available from Matomo 4 and newer.

Visits from search engines or campaigns are not recorded, Matomo shows « There is no data for this report » for all Referrers reports.

There are a few possible explanations:

  • Are your pages tagged correctly?
    If you click on your website in a search result, and look at your page source, can you see the Matomo (Piwik) tracking code? Make sure the Matomo tracking code is installed on all the pages you want to track, and is not within an iframe. We advise to put the Matomo code just before the </body> tag.
  • Are you using a redirect on your website landing page?
    If you are using a redirect, the visitor browser may lose the referer information. If you are tracking campaigns, and the landing page has a redirect, the URL loaded after the redirection will have lost the URL parameters. Make sure that your visitors arrive directly on the page with the Matomo tracking code installed.
  • Is your website using HTTPS (SSL)?
    Most websites these days are running over HTTPS. When someone is visiting another website over HTTPS and clicking on a link to your website, you want to make sure that the link to your website also references the HTTPS version of your website. (If a user on a HTTPS website clicks on a link to a HTTP page, the referrer will not be passed to the HTTP page). Therefore to make sure that all your referrers are correctly tracked in Matomo, you need to make sure that your website works on HTTPS and also that your links from other websites to your website use the HTTPS version of your website URLs.
  • Matomo only records 1 referer by visit, which means that only the first referer used to access the website will be recorded.
    If you search for a keyword in a search engine, click on your website in the search engine results, and land on a page with the Matomo tracker, you may expect to see the keyword in your Matomo reports.
    However, if you visited your website less than 30 minutes ago, Matomo will recognize you as an known visitor on the website, will record your page view, but will not update your visit referer. Matomo only record the first referer of a visit. When testing Matomo and search engine detection, make sure you make the test more than 30 minutes after your last page view on your website.
  • Check that the Matomo domain name in your Javascript tracking code is correct (this URL is in the second line of the Matomo tracking code). There have been cases of missing referrers when the Matomo JS code in the pages points to a URL that returns a 302 response instead of the final destination. It seems that some webserver compromise the tracking request when such redirects occur. Check in particular if the URL (doesn’t) contains « www. ». Also, if the server does an automatic redirection from http to https which also affects tracking requests to piwik.php, it might create problems such as missing referer data. Make such any http->https redirection excludes piwik.php requests.

If you have some data in Acquisition reports, but you’re finding discrepencies with other tools, see the FAQ: Visits and clicks data provided by search engines or affiliates do not match the acquisition reports in Matomo?

Matomo doesn’t track Downloads and clicks on Outlinks on my website.

Matomo (Piwik) should automatically track clicks on Download files (with a known extension, eg. jpg, png, exe, zip, etc.) and clicks on Outlinks (links to other websites) using Javascript click handlers. There are a few reasons why this could fail:

  • Conflicting Javascript code
    In some rare cases, Download and Outlink tracking doesn’t work in Matomo is because your page is using another Javascript script or library which sets click handlers as well. If a third-party click handler returns a value, it is causing the browser to cancel other registered click handlers. Instead they should return false. Most scripts and libraries are doing it correctly, but you might have to manually edit your Javascript code to return false in onclick events.
  • Matomo doesn’t respond fast enough and user is redirected to the click target
    Matomo click handler works by adding a small delay during which the request is sent to the Matomo server. If somehow the request doesn’t reach the server within this delay, the request will be not be tracked and the user will be redirected to the clicked download file or to the external website. You can increase this delay, from the default of 500ms (0.5 second), by adding the following in the Javascript code, after the piwik.getTracker(..) line:

    _paq.push([‘setLinkTrackingTimer’, 750]); // increase to 750 milliseconds

  • You’re using an old browser version
    For example there were known WebKit bug where the tracking request was interrupted. One workaround is to add the target= »_blank » attribute to anchor elements.

  • Track a file extension not known to Matomo yet, see the developer guide Customise the type of files tracked as downloaded.

  • Manually track a click as a download, when automatic download tracking does not work for some reason, you can Manually record a click as a download.

  • Enable Send Beacon in the Matomo JavaScript tracker The Send Beacon is enabled by default in Matomo 4, but can be enabled manually if necessary.

If this doesn’t help solve the issue, you can find additional relevant information in this FAQ: Matomo is not tracking outlinks clicks to my own websites

Matomo doesn’t detect accurately the Country and/or Continent of my visitors.

To improve Visitor Country detection, you should configure Geo Location in Matomo (Piwik) (click to learn more).

If you are not using Geo Location, Matomo is guessing your location from the language locale disclosed by the browser, e.g. en-us -> country is set to USA, fr-fr -> country is set to France, etc. In some cases, Matomo will guess the location when the region is omitted, e.g., fr -> France. This can be disabled from config/global.ini.php (or overridden in your config.ini.php):

[Tracker]
enable_language_to_country_guess = 0

If you want to improve the country detection accuracy in Matomo, setup Geo Location now.

Matomo is slow! It takes a long time to load widgets, reports and pages.

There are a few possible reasons that Matomo (Piwik) could be slow to load:

  • By default, Matomo reports are processed when you request them in the User Interface. Please see How to setup auto archiving of your reports every hour? to automate the generation of Matomo reports.
  • If you are using Matomo on a website (or thousands of websites) tracking millions of pages per day, please check out the doc: How Matomo for high traffic websites.
  • If your server uses NFS-mounted storage (for example if you are using OVH mutu webhost), widgets might load very slowly even if you are not tracking a lot of data. This is because Matomo by default uses « file based sessions » which are very slow when using NFS storage. The solution is to change a setting to enable Database session storage.

You may also be interested in: will the Matomo Analytics JS Tracker slow down my website?

I get ‘Oops… there was a problem during the request.’ or ‘Internal Server Error’ or ‘500 error’ or the ‘White screen of death’. How do I proceed?

Matomo may in rare cases display an error such as ‘Oops… there was a problem during the request.’ or ‘Internal Server Error’ or ‘500 error’.

When you have such problem, please follow the following steps to resolve the issue:

  1. The most common solution to the message Oops... there was a problem during the request. is to setup Auto-Archiving in your Matomo by following these two steps:
    a) Enabling the crontab to run the core:archive command and
    b) Disabling « Archive reports when viewed from the browser » in the General Settings.
  2. If the error persists, or you’re getting a white screen/page (sometimes called the ‘White screen of death’), it indicates that there is a problem on the server: check in your web server error log file for an error message.
  3. When you find an error message in your server error log, then search for this message in the Matomo FAQ.
  4. If you do not find the answer in a FAQ, maybe it is a bug in Matomo. Search for the message in our issue tracker here.
  5. If you still have a problem and could not resolve it with those steps, please ask in the forums.

Matomo does not track visits on SSL / HTTPS pages.

When Matomo (Piwik) does not record your secure SSL traffic, you need to check that your Matomo server is correctly configured to be accessed over SSL / HTTPS.

Why do Matomo data reports differ from Google Analytics and other analytics tools?

Often you want to compare the data from different web analytics tools together, for example comparing Matomo reports with Google Analytics reports and find whether they are similar or whether one is tracking more or less data than the other.

When you compare compare Google Analytics reports and metrics to the equivalent in Matomo, you should expect both Matomo and Google Analytics reports to be very similar and no more than 5% or 10% different for numbers of visits/sessions, pageviews, etc. (Except if your Google Analytics reports are sampled while Matomo is always accurate and does not sample data).

When you compare Matomo reports to another web analytics tool, there are several aspects to consider that could explain why numbers are different between the different analytics solutions. Please find the list below:

  • DoNotTrack support: Matomo (Piwik) by default respects the DoNotTrack setting. If visitors have selected not to be tracked in their browser, Matomo will not collect information about them. If you suspect many of your users are using DoNotTrack, you can disable it in the Privacy settings. This features works in the JavaScript tracker. When importing logs all visitors and actions will be tracked as DoNotTrack is not available in server log files.
  • Bots and Spiders tracking: By default Matomo uses a Javascript tracker which automatically only records « real » human activity and excludes all bot activity. This leads to more accurate reports. If you compare Matomo reports to Google Analytics and notice a large discrepancies (over 5%) you may try to disable bot tracking in GA. To do this in Google Analytics go to Admin settings and navigate to View Settings under the View panel. Find the checkbox « Exclude traffic from known bots and spiders » and select it. Then both Matomo and Google Analytics will exclude all bot traffic. (PS: Matomo can be configured to enable tracking of search engine bots).
  • Presence of Javascript code tag: when comparing Javascript-based statistics (eg. number of unique visitors), you have to make sure that both javascript tags are present on all pages you want to track. If you’re seeing some pages that are tracked in one tool but not the other, maybe you have forgotten to add one of the JavaScript tracking codes on some of your pages.
  • Position of Javascript code tag: it is recommended to put the Matomo tracking code at the end of your </head> tag in your pages.
  • Higher « Direct Entry » visits in Matomo When tracking the acquisition source of visitors, Google Analytics stores and uses campaign data for up to 6 months and attributes subsequent direct entry visits to the original campaign acquisition source. (So Google Analytics will report a higher number of visits attributed to « Campaigns » because these visits used a campaign in the previous 6 months.)
    Whereas Matomo tracks any new « Direct Entry » visits as direct entries and does not attribute these new « Direct Entry » visits to their original acquisition source. With Matomo’s Multi Channel Conversion Attribution plugin, you can apply different attribution models to your goal conversions.
  • Identifying Visitors: Matomo uses a javascript based tracker, and keeps count of unique visitors using a first party uuid cookie, as well as a visitor recognition heuristics algorithm (based on IP address and user settings: learn more). Some other tools only use cookies, only use IP, or a combination: we found that the way Matomo tracks visitors gives us really good accuracy and avoids creating artificial visits.
  • Tracking method: Other softwares which are using server logs) for data analytics (such as AWStats, Webalizer, Analog, or any custom server-side data collection script) would record all traffic, including search bots or spam bots. When your Matomo numbers are much smaller than your other tool, check that you are comparing Matomo with a similar web analytics tool which can also exclude all bots and spam traffic like Matomo does.
  • Hits vs Visits: Log analyzers softwares will typically report « hits ». Hits generally count all http requests to your websites: pages, images, css, javascript files, etc. Matomo reports page views, unique visitors, visits, etc. which are expected to be much less than the number of hits.
  • Record loaded page: when the Matomo javascript code is located at the end of the page, Matomo will only record page views for page that are finished loading. Log Analyzers would also record page requests that have been « cancelled », eg. when the user hits the Back button before the page is displayed.
  • IP addresses exclusions: when you have configured Matomo (or Google Analytics) to ignore users with specific IP addresses, make sure to setup the same IP exclusion rules across both tools.
  • Matomo does not sample the data so you get to see 100% of the visits that were tracked in the reports. Other tools like Google Analytics will sometimes sample reports including segments.

Conservative counting is definitely best – it makes your statistics more realistic on what you are trying to measure. Most analytics packages are used to measure relative upswings, we recommend using the same tool for all measurements and relative comparisons.

See also the FAQs:

If you migrate from Google Analytics to using Matomo, you can import your historical Google Analytics data and reports, see our Import Google Analytics data user guide to get started.

You may also be interested to see how Matomo compares in general to Google Analytics, HotJar and WP-Statistics.

After I updated Matomo, it stopped working (blank page, widgets not loading, error message, etc.). How can I fix this?

When you upgrade Matomo (Piwik) to the latest version, it sometimes happen that Matomo stops working — especially when the User Interface is not working (blank white page, widgets not loading, error message, etc.).

There are a few things to check that will most likely resolve the User Interface issue you are having:

  • 1) Delete your browser cache or try to access your Matomo with a different browser. If it still does not work…
  • 2) Delete all files in piwik/tmp/*. After deleting the files and directories, refresh the page. If it still does not work…
  • 3) Activate the display of PHP errors in your web server configuration. This may turn your white page into a useful error message page.
  • 4) Check your web server error logs. Maybe your error log will contain an explanation for the problem. If the log file has no Matomo related error…
  • 5) Reupload all Matomo files from the latest version. Sometimes, there are errors while uploading files and some of your Matomo files were maybe not overwritten by the latest version. Upload all files again, and check in your FTP software that the upload was successful.

Also, check out the other FAQs in this « Troubleshooting » category, as there might be other solutions for your problem.

If it still does not work, please search the Matomo Forums or search this website, and if there is no post about your problem, please create a new topic.

How do I configure my server to let Matomo serve HTML files?

For Matomo (Piwik) to work correctly, your web browser should be able to download from your Matomo server a set of HTML files. This FAQ explains what are various ways to configure your server to deliver Matomo HTML files.

To test whether your server can serve HTML, visit this URL: demo.matomo.cloud/plugins/MultiSites/angularjs/dashboard/dashboard.directive.html (replace demo.matomo.cloud with your Matomo URL). If this HTML page on your server looks the same as this page then your server is configured properly to serve HTML files!

If the test does not succeed then you need to enable your server to correctly serve HTML files for Matomo:

  • if you are using Apache as webserver, put AddHandler text/html .html in the <directory> section of the Apache host config. Restart the webserver.
  • if you are using Nginx, check out the Piwik-Nginx configuration. Note: make sure you replace the corresponding line in the piwik-nginx configuration with your own domain(s): valid_referers none blocked *.mysite.com othersite.com; (if that is too much of a hassle for you then just comment out the valid_referers block.)
  • if you are using the module Pagespeed in your server, please note that (pagespeed extension does not work with Matomo). You may disable pagespeed for Matomo by adding this to the apache config: ModPagespeedDisallow "path_to_piwik_here"
  • if you still have issues serving HTML files, verify that your server does not redirect requests from index.php to index or from index.php to /. Such redirects may cause loss of POST variables causing issues.
  • if you still have issues serving HTML files, try to recursively change permission on the path/to/piwik/plugins folder (chmod -R 755 plugins/)

If you have other suggestions to add to this list, please use the form in this page.

Note: if you get the error message client denied by server configuration then you are experiencing this issue. You may follow the list of suggestions above to get it resolved.

The graphs (pie chart, bar chart, evolution graph) are not showing in my Matomo.

If you are not seeing Graphs in Matomo (Piwik), the most likely reason is that you are using Matomo < 1.5 which are using Flash graphs, and you do not have Flash enabled in your browser.

As of Matomo 1.5, graphs in Matomo are drawn using open source technologies supported in all modern browsers: see Canvas and Jquery graphs blog post.

The sparklines (small graphs) are not showing in my Matomo.

The GD library is not installed on your server. This library is required to produce the sparklines. Please ask your system administrator or your web host to install php5-gd for you.

On linux, you can install php-gd by executing apt-get install php5-gd on debian type systems, then restart your webserver.

If you are using Apache webserver and a module called mod_security, please disable this mod_security module as it may sometimes cause Sparklines graphs to not display.

Matomo reporting UI doesn’t have any css style or, the menu text appears on a white background, or I get JavaScript errors in the Matomo UI. How to fix this display problem?

Firstly, when you experience this issue please check that any Adblocker extension in your web browser is disabled, as it may mistakenly block the Matomo (Piwik) Javascript or CSS files.

If after disabling all adblockers you still experience the issue, read on.

To improve performance, Matomo tries to automatically combine all CSS stylesheets and Javascript files into two large files, instead of having to download 20 individual files. However, on some webhosts, PHP scripts have a max execution time and if the server is overloaded, the script that merges all files together can take more than the time limit.

  • Ask your webhost to increase the max_execution_time in your php.ini file, for example to 30 seconds.
  • If you can’t change this setting, you can alternatively disable the feature to combine together CSS and JS files. To disable this feature, edit your config/config.ini.php and add the following:
    [Development]
    disable_merged_assets = 1

(if you are using Matomo 2.4.1 or earlier, set this setting under the [Debug] category)
Then, delete your browser cache and refresh Matomo: after a few seconds, it should display correctly again!

How do I configure Matomo on a server without Internet?

Matomo tracking, reporting, API do not require access to the Internet, for example if you are running in an Intranet or an infrastructure without any Internet connection.

What optional features in Matomo use the Internet

By default a few optional features which use Internet such as:

  • Email notifications when there is a new version of Matomo platform available (important for security)
  • the Marketplace (installing new plugins and downloading latest versions of plugins and themes).
  • Downloading the latest list of Devices to detect
  • Downloading the latest list of Referrer spammers
  • Downloading the latest list of Search Engines and Social networks
  • Downloading the latest geolocation database for more accurate geolocation of users
  • Sending SMS/text messages with scheduled reports
  • Getting the SEO widget to show the SEO report

Problems encountered when there is no Internet

When Internet is not available, usually these features will timeout after 10 seconds or so and display a warning/error message. Some examples of messages are: curl_exec: Connection timed out after 3000 milliseconds or curl_exec: couldn't connect to host or this error: Warning: file_get_contents (http://plugins.matomo.org/api/2.0/plugins) failed to open stream: HTTP request failed!.

Follow the instructions below to fix this error.

Allow Internet connections to official Matomo hostnames

We recommend if possible to allow Internet connection to the following hostnames:

  • api.matomo.org (getting notified when a new release is available including security releases),
  • builds.matomo.org (for the one-click update to work),
  • plugins.matomo.org (for the Marketplace).

This is usually done on your Network or in the Firewall used, so please reach out to your technical team responsible for the network or servers.

Alternatively you can disable all features that use Internet connections as described below.

Completely disable all Internet features

To completely disable all Internet-related features, please add the line enable_internet_features = 0 to the [General] section of your config/config.ini.php file.

Downloading plugins without Internet on the Matomo server

You can still download free plugins, as well as purchase premium plugins, directly on the Marketplace using your browser.

After you download or purchase plugin(s) on the Marketplace, you can install them manually in your Matomo.

Disable the Marketplace feature

If you are using a Matomo version before 3.6.0 or just want to disable the marketplace, you can do this by adding enable_marketplace = 0 to the [General] section of your config/config.ini.php file.

When tracking visits on an intranet website, Matomo assigns all page views to a few visitors who have very high page views count. How to fix it?

On Intranet websites, often most users have the same IP address, and often the same browser and configuration settings. This causes Matomo (Piwik) to believe that most page views come from the same visitor. To fix this on Intranet websites, see this FAQ: Enabling Matomo on Intranet websites.

The Matomo Javascript code shows a red cross (on IE) or a broken image icon instead of the 1*1 transparent Pixel, what is the issue?

When Matomo (Piwik) is showing a red cross image, or a broken image icon, it means that tracking visits is failing on your Matomo installation. It is not expected and should be investigated to fix the root of the problem as soon as possible (in the meantime, your visits are most likely not recorded).

To see where the error comes from, open your website in Firefox, right click on the broken image icon, and click on « View Image ». This should redirect you to the URL « yourwebsite.com/piwik/piwik.php?… » and the error message should be showing.

If the error message mentions MySQL, the error might come from a broken mysql instance or tables. Try to « repair » your MySQL tables (using phpMyAdmin for example).
If the error mentions « failed to open stream: No such file or directory » this might be caused by missing Matomo files. Make sure all Matomo files are properly uploaded.
For other errors, try to search on the search engine on Matomo.org.
You can also try the Matomo support forums for more help.

How do I configure Matomo when mod_security (or CA SiteMinder) is enabled?

Unfortunately, Matomo (Piwik) is not compatible with the Apache web server module mod_security nor with CA SiteMinder. If your web host uses mod_security to block requests containing URLs (eg. hosts like HostGator, The Planet), you should contact your provider to have your Matomo application whitelisted and have mod_security disabled for Matomo.

With mod_security (or CA SiteMinder) is enabled Matomo will look like it works but these security modules create major bugs in Matomo, including major data loss as requests are mistakenly discarded by the server! For more information, see this ticket on Matomo issue tracker.

If you are using Plesk, see our guide on how to install Matomo on Plesk which includes a section on how to Disable Web Application Firewall (ModSecurity).

Some of the error messages you may see in Apache error log when using mod_security include client denied by server configuration:. When the other tool CA Siteminder is enabled, you may get: Due to the presence of characters known to be used in Cross Site Scripting attacks, access is forbidden. This web site does not allow Urls which might include embedded HTML tags..

Almost all reports and dates are working fine except one or a small number of days/weeks/months/date ranges which display zero visit. How do I fix this issue and restore the missing data?

In rare cases, Matomo (Piwik) will show « no data » for a subset of data, for example for one day, one week or one month, while other periods will work fine and report all data as expected.

How to solve this problem?

Congratulations! you should have now restored the missing data and likely prevented this issue from occurring in the future.

What causes this issue in the first place?

In short, there could be multiple reasons and it’s difficult to know.
Unless this was an ongoing consistent issue it wouldn’t be worth investigating as this may be the only time it happens.
But if you continue to have this issue with invalid reports or incomplete reports, we recommend that you confirm with your team that you have setup the crontab with the MAILTO line, so that you get an email whenever the crontab fails.

MAILTO=your-email@company.com
1 * * * * php /path/to/matomo/console core:archive --no-ansi >> /path/to/private-logs-folder/cron-matomo-archive.log

In this crontab entry replace your-email@company.com by your Matomo system administrator team email. If there is an error during the script execution, the script output and error messages will be sent to this address.

It is helpful to review and monitor these errors and take actions to prevent these missing data reports issues.

The numbers from Transitions don’t match other numbers shown in Matomo. Why?

The Transitions Plugin gives you a report that shows the things your visitors did directly before and after viewing a certain page. There are few cases, where the data displayed in Transitions is slightly off compared to what you might expect.

The number of pageviews shown in the pages report may not exactly match the number of pageviews in the Transitions report. There are several possible explanations:

  • Since the pages report is pre-archived, it shows the numbers of time the archiving was launched. Transitions doesn’t use the archives but retrieves the number directly from the logs. So if you have more pageviews in Transitions and you are viewing a period that includes today, this might be why the numbers don’t match.
  • The pages report sometimes aggregates multiple URLs into one row. For example when you track multiple domains, example1.org/home.html and example2.org/home.html will both end up in the row /home.html in the pages report. Transitions is based on unique URLs and will open on the URL with most pageviews that was aggregated into the row of the pages report. So if example1.org/home.html had more pageviews that example2.org/home.html, Transitions will open on the URL example1.org/home.html and show only statistics for this page.
  • Before version 1.9, Matomo (Piwik) recorded URLs with the hash part (e.g. example.org/home.html#something) but didn’t show the hash part in the pages report. When you have tracked pages with different hash parts, the previous bullet point applies and you will see Transitions for the unique URL that had most pageviews of all the URLs aggregated into the row of the pages report you clicked on.

Another case of odd numbers is when the sum of the groups on the left does not equal the total number of pageviews. If you think that this is the case, first make sure that you have included the page reloads in your calculation. If the numbers still don’t match, read on.

This can happen when there were downloads or outlinks tracked directly before views of the page in the center. We could have added a group on the left « From Downloads » and « From Outlinks » but we decided not to, as it would make the interface more complex unnecessarily. Since we didn’t want to add the missing pageviews to any of the other numbers, the sum of all groups that are shown might differ from the total number of pageviews.

The main limitation of Transitions is that it only works on the period of time you still have the logs for. If you have set up Matomo to delete old logs, the pages report will still contain data from before because the reports were archived. Since Transitions reads its data directly from the logs it can only work if you still have the logs.

Another reason for an apparent case of incomplete data, is connected to the truncation of reports. Matomo doesn’t necessarily report every unique URL on your website, but instead there is a limit for the maximum number of rows in the pages report (which can be changed). Usually that’s not a problem because the number is high and if you haven’t heard about it yet, it probably doesn’t apply to you. But if this happens on your data, there might the case that for some days of a period, the page is listed under Others but not for other days. The report for the period is the sum of the daily reports and therefore it can happen, that a URL is « missing » on some days and not on others. The sum of the pageviews will be too low in the actions report but Transitions reports the number of pageviews correctly. It can do so because it doesn’t use the archives but the logs.

We hope you enjoy the Transitions feature. We appreciate if you let us know what you think about it!

How do I check that my Matomo SSL Server is correctly configured?

If your website has HTTPS / SSL pages, to ensure that all your visitors actions will be tracked on all browsers, you need to check that your SSL Server is correctly configured. We recommend to take the SSL Server test, for the URL of your SSL Matomo (Piwik) server. In particular you should check that « Chain issues » is « None », otherwise some browsers (for example on Mobile devices) will not connect to your Matomo SSL Server and you will lose some visitor tracking data.

How do I delete historical Matomo data? (data retention for old web analytics raw data logs and/or old processed reports)

Matomo (Piwik) tracks visitors activity, and then computes aggregated reports. The settings page lets you

  • 1) Delete the Tracking Logs (RAW data) and / or….
  • 2) Delete the old processed stats (archived reports)

Delete old RAW data (old tracking logs)

You can configure Matomo to automatically delete your older tracking logs from the database. Deleting old logs has many advantages: 1) it will free significant database space, 2) which will slightly increase performance, 3) for Privacy reasons, it is sometimes recommended to keep detailed logs only for 6 months or so, and remove older data.

To configure Log delete in Matomo, login as the Super User, click on Administration > Privacy > Anonymize Data > Delete old visitor logs. You can then configure to Delete logs older than N days, and execute the log purging every day, every week or every month. When ‘Delete old logs’ is enabled, only the raw logs of activity will be deleted from the database. Specifically, only the Mysql tables starting with matomo_log_* are affected.

You can delete old logs data in various ways: by using the UI, a console command, or even SQL queries. Read this FAQ for more information: How do I delete old visitors statistics for a given website and/or date?

Important: When you enable automatic log deletion, you must ensure that all previous daily reports have been processed, so that no data is lost. See this FAQ for more information.

What is the impact of deleting historical RAW data?

If you have properly setup the auto archiving script (see important note), you will still access all historical reports (even when RAW data is deleted). But there are important points to be aware of:

  • Deleted data: All deleted data is lost forever.

  • The Visits Log will be empty across the periods without RAW data.

  • Transitions report: The Transitions report is processed in real time, using the logs. When deleting old log data, the report will still partially work but only display transitions for the days that still have log data.

  • Unique visitors metrics: The Unique visitors metrics for Weeks, Months, Years will be available only for those date ranges that still have log data. Unique visitors metric will still be processed for days.

  • If you were to create a new custom report, the data included could only go as far back as the amount of RAW data you have.

  • Roll-up reporting also relies on RAW data so for the period of missing data roll-up reporting will not be available.

  • If you were to invalidate data across a period with missing RAW data you do not need to be concerned about losing report data, as Matomo will detect the RAW data is missing and maintain the current archived data.

Delete old reports data

If your Mysql database space is limited, you can also Delete old reports in Matomo > Administration > Privacy. You can choose to keep daily, weekly, monthly and / or yearly data. We recommend keeping monthly and yearly data as an interesting dataset.
If you enable any of the 2 features to delete old data, the Database estimate size will refresh and give you an idea how much space you would save using the feature. If you cannot wait for the next automatic tasks schedule, you can also force the purge by clicking on ‘Purge Now’.

How do I check if my MySQL user has all required grants

To check if your MySQL user has all required grants / permissions, connect to your MySQL database using the same database user that Matomo uses (or WordPress if you are using Matomo for WordPress).

Now execute the following query:

    $ mysql> SHOW GRANTS;

Matomo requires the following grants and the above query should list all of below grants or ALL PRIVILEGES:

SELECT, INSERT, UPDATE, INDEX, DELETE, CREATE, DROP, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES

If any of the above grants are missing, you need to grant the missing permissions like this:

    $ mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, INDEX, DROP, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES ON matomo_db_name_here.* TO 'matomo'@'localhost';

In these instructions:

  • replace matomo_db_name_here with the name of your MySQL database
  • replace matomo by your chosen MySQL username (or simply use matomo).
  • replace localhost by your MySQL host

I would like to import an existing Users database (login, password, emails) in Matomo, but the usernames and passwords are more permissive than what Matomo allows. How do I disable the checks on the Logins & Passwords?

When you automatically import your existing userbase in Matomo (Piwik) using the UsersManager API, you might want to disable the check of minimum length and valid characters for the User’s login and password.
In particular, Matomo requires a password at least 6 characters long, and a login string that must contain only valid characters (ie. letters, @, etc.).
You can disable these checks by adding in the file config/config.ini.php the following:

[General]
disable_checks_usernames_attributes = 1

Matomo doesn’t show me when new updates are available, and the SEO plugin doesn’t work.

Your firewall may be blocking outbound HTTP requests. If you have a HTTP proxy (e.g., squid), you can configure the forward proxy as follows.
Edit your config/config.ini.php and add the following:

[proxy]
host =      ; Proxy host: the host name of your proxy server (mandatory)
port =      ; Proxy port: the port that the proxy server listens to. There is no standard default, but 80, 1080, 3128, and 8080 are popular
username =      ; Proxy username: optional; if specified, password is mandatory
password =      ; Proxy password: optional; if specified, username is mandatory

Once configured, Matomo (Piwik) will contact external hostnames using this proxy server.

« Segmentation fault Error ». Matomo reporting or via cron crashes with Segmentation Fault error. What to do?

Unfortunately, Segmentation fault Matomo (Piwik) errors mean that the lower level software has crashed in some unexpected fashion. In this case, most likely PHP or some of its specific modules (PDO, mysqli, etc.). It is possible to overcome this issue by updating these softwares.
If you get the Segmentation fault error, the solution is to:

  • Upgrade Matomo and make sure to use the latest version
  • upgrade PHP to the latest version
  • upgrade PDO (and/or mysqli) to the latest version.
  • you may also try to switch from PDO_MYSQL to MYSQLI in the config/config.ini.php ; edit the line « adapter = […] »
  • if you still get the error, try disabling extensions such as eAccelerator, xcache and/or Suhosin, if you are using one of them.
  • if you still get the segmentation fault error at this point, try the suggestion in this issue (if it works for you, please post a comment in this issue).

You should now have a working Matomo instance that does not crash, congratulations.

I get the error message: « Fatal error: require_once() [function.require]: Failed opening required XYZ in /path/piwik/XYZ.php on line X ». How can I get Matomo to work?

This error message means that PHP couldn’t include a file that Matomo (Piwik) requires. Please make sure all Matomo files are correctly uploaded on your server. You can reupload the missing files by looking at the error message, or reupload all Matomo files and try again: this should work!

Emails from Matomo are not being sent, how do I troubleshoot and solve the issue?

When emails from Matomo are not being sent, for example scheduled email reports or password reset emails are not sent, or you may be getting the error [Zend_Mail_Protocol_Exception] 5.1.7 Bad sender address syntax while executing the core:archive console command via crontab, then please follow the steps below to likely solve this issue.

Edit your config/config.ini.php and under the [General] category add the following:

noreply_email_address = "noreply@your-domain-here.com"
login_password_recovery_email_address = "noreply@your-domain-here.com"
login_password_recovery_replyto_email_address = "noreply@your-domain-here.com"

This should fix the issue and your Matomo emails should now be sent.

If your emails are still not sent from Matomo, then please run the following command (requires Matomo 3.10.0) to send a test email (replace your-real-email-address@example.com by your real email address):

./console core:test-email your-real-email-address@example.com

And if you see any output please contact us to let us know about it.

Finally if you are not able to receive emails from Matomo with the default configuration, we recommend to try to configure a SMTP server to send all emails from Matomo as this will likely solve the issue.

If you are receiving an SMTP Error: Could not authenticate then read here how to resolve this issue.

How do I fix the error « Parse error: syntax error, unexpected T_STRING in … »

If you get this error, this means that the PHP running on your webserver is too old. Please ask your webhost or sysadmin to upgrade your PHP to the latest PHP version: see Matomo (Piwik) requirements for further details.

If you have trouble running Matomo, consider using one of our Official Matomo Hosting solutions.

How do I solve issue ‘An error occurred: Cannot connect to the database’?

When Matomo (Piwik) displays an error message An error occurred: Cannot connect to the database this means that Matomo was not able to connect to your Mysql database.

To solve this problem you can:

  • Contact your system administrators and ask them to verify that the Mysql server is up and running
  • If your Mysql server is up and running, maybe the username or password used to connect has changed? To update the Mysql connection information, edit your configuration file config/config.ini.php to view and edit your connection details.

What should I do when I get the error message: SQLSTATE[HY000] [2002] Can’t connect to local MySQL server through socket ‘/var/lib/mysql/mysql.sock’ (11)

This means that Matomo (Piwik) could not connect to your MySQL database. If you are on a dedicated server, you can try to restart the Mysql server by running, for example,

/etc/init.d/mysql restart

. If you are on a shared web hosting, we recommend contacting your web host and ask them to investigate why it fails to connect to the Mysql server.

How do I fix the error « SMTP Error: Could not authenticate. »

This error happens when the SMTP authentication credentials are misconfigured/invalid.

To resolve this issue, follow these steps:

  1. Log in as a super user.
  2. Go to Administration – System – General Settings.
  3. Scroll down to the section ‘Email server settings’.
  4. Check the Email server settings and correct them as needed. If they are correct, try to use the same credentials in an email client to test if they work there too. If the issue persists after configuring the correct credentials, please contact us.

I get the error « Warning: gzuncompress() [function.gzuncompress]: data error » when looking at my Matomo reports.

This error happens in very rare cases where, for some unknown reasons, the data was not properly recorded in the database. In Matomo (Piwik), all reports data is compressed (gzip) and then stored in the tables matomo_archive_*.

To fix this issue, look at the error message and search for « matomo_archive_blob ». For example, if the error looks like:

#0 Piwik_ErrorHandler(2, gzuncompress() [function.gzuncompress]: data error, /path/piwik/core/Archive/Single.php, 250, Array ([name] => Referers_searchEngineByKeyword,[typeValue] => blob,[table] => matomo_archive_blob_2009_05,[...]

You can find « matomo_archive_blob_2009_05 ». Please delete this table in your Matomo database. Matomo will process it again next time you are viewing reports. This will fix the issue.

Emails sent from Matomo use the email address @defaultHostnameIfEmpty.example.org, how do I specify my domain name instead?

By default Matomo (Piwik) will try to detect the current Hostname and use it in all emails sent. In some cases, the hostname cannot be detected and Matomo will use « defaultHostnameIfEmpty.example.org ». You can specify your domain name to appear in From: email addresses by adding the following lines in your config/config.ini.php file:

[mail]
defaultHostnameIfEmpty = mydomain.com

This will affect all emails sent from Matomo: Password reminder, Email reports. You can also change the default email address « From: » in PDF reports emails.

How do I fix the error « 1118 Row size too large. The maximum row size for the used table type, not counting BLOBs, is 8126. »?

The full error message typically looks like this:

The error was: SQLSTATE[42000]: Syntax error or access violation: 1118 Row size too large. The maximum row size for the used table type, not counting BLOBs, is 8126. This includes storage overhead, check the manual. You have to change some columns to TEXT or BLOBs

You usually have two options to fix this.

Option 1 – changing the row format (recommended)

For the table in question run a query like this and make sure to replace log_visit with the name of the table that is causing this issue:

ALTER TABLE matomo_log_visit ROW_FORMAT=DYNAMIC;

Option 2 – changing the type of some existing custom dimensions or custom variables

if you use many custom dimensions

If you are using many custom dimensions, then converting some of them to TEXT might help. You can convert as many columns as needed. This can also be useful if you are trying to add more custom dimensions but you cannot add more slots because you ran into this limit.

ALTER TABLE matomo_log_visit MODIFY COLUMN custom_dimension_1 TEXT, MODIFY COLUMN custom_dimension_2 TEXT, MODIFY COLUMN custom_dimension_3 TEXT, MODIFY COLUMN custom_dimension_4 TEXT, MODIFY COLUMN custom_dimension_5 TEXT;

If you use more than 5 custom dimensions, you can add more statements in the query for example: , MODIFY COLUMN custom_dimension_6 TEXT.

if you use many custom variables

If you have many custom variables instead you can convert them to TEXT as well so they no longer count to the MySQL row size:

ALTER TABLE matomo_log_visit MODIFY COLUMN custom_var_k1 TEXT, MODIFY COLUMN custom_var_v1 TEXT, MODIFY COLUMN custom_var_k2 TEXT, MODIFY COLUMN custom_var_v2 TEXT;

Depending on your configured database table prefix you might need to replace matomo_log_visit with piwik_log_visit or log_visit for example in the SQL queries above.

Matomo reports this error and fails: « Fatal error: Allowed memory size of X bytes exhausted (tried to allocate X bytes) ». What should I do?

You must increase PHP memory limit. See this page for more info.

How do I fix the error « Call to undefined method MaxMind\Db\Reader::getWithPrefixLen() »?

This FAQ applies to you if you are seeing an error that looks like this:

Call to undefined method MaxMind\Db\Reader::getWithPrefixLen() in vendor/geoip2/geoip2/src/Database/Reader.php

If that’s the case, please check if you have maybe the MaxMind PHP C extension installed.

If you don’t know if that’s the case, you can execute the command php -i on the command line and look if the MaxMind extension is installed. To solve this problem you will need to disable this extension and restart your webserver. If you don’t know how to do this, we recommend contacting your system administrator or your hoster.

Matomo for WordPress

If you are using Matomo for WordPress there’s also a chance that a different plugin bundles an older (unsupported) version of the MaxMind. In this case you could try disabling other plugins to see if this fixes the issue. In such a case please create an issue in our issue tracker and let us know which plugin is causing this issue. If you don’t know which plugin is causing this error you can also instead post your Matomo for WordPress system report in a new issue and we will try to reproduce it.

Matomo reports this error and doesn’t continue: « Fatal error: Maximum execution time of 30 seconds exceeded in … »

Your PHP is configured to stop running a script after some time, generally 30 seconds. When Matomo (Piwik) is used on a websites with few thousands visits per day, then this limit might not be high enough. To fix this, modify in your php.ini the max_execution_time value to zero (which means no time limit):

max_execution_time = 0

This will ensure that Matomo always has enough time to process your analytics reports.

To find where is your php.ini file on your server, you can follow the following steps: create a test.php file and add the following code:

 <?php phpinfo(); ?>

and open it in browser, it will show the file which is actually being read by PHP running on your webserver. It will also show your currently set max_execution_time value.

How do I fix the error « Mysql Server has gone away »?

The MySQL server has gone away (error 2006) has two main causes and solutions:

  • Server timed out and closed the connection. To fix, check that wait_timeout mysql variable in your my.cnf configuration file is large enough, eg wait_timeout = 28800
  • You may also need to increase the innodb_log_file_size mysql variable in your my.cnf configuration to for example innodb_log_file_size = 128MB or higher.
  • Server dropped an incorrect or too large packet. If mysqld gets a packet that is too large or incorrect, it assumes that something has gone wrong with the client and closes the connection. To fix, you can increase the maximal packet size limit max_allowed_packet in my.cnf file, eg. set max_allowed_packet = 128M, then restart your MySQL server: sudo /etc/init.d/mysql restart
  • Database server ran out of space. This can occur when performing an update to the Matomo database that requires DB Schema changes (Especially for large databases).

Once you’ve made these changes, and restarted your MySQL or MariaDB server, the issue should be fixed and no more error triggered. If not, try increase the 128M values to 256M for example. In websites with a lot of traffic and data, you might even need to increase the value to 1024M.

If the above changes do not resolve the issue and if you are using MYSQLI adapter in Matomo, try switching to adapter = PDO\MYSQL in your config/config.ini.php file.

You may be interested to learn more about Matomo Analytics to measure your websites and apps and keep control of your analytics data.

How do I fix the Mysql « Error while sending QUERY packet »?

The MySQL server error « Warning – Error while sending QUERY packet » has two main causes and solutions. Please check this FAQ for the solution.

Graphs in PDF/HTML reports and/or Matomo Mobile do not display characters correctly in my language (display squares instead).

To display unicode characters in the Static image graphs, please see this FAQ.

When I use force_ssl=1, I get « Too many redirects ». Also when I use https, CSV/PDF reports and graphs don’t work.

If you’re not using a reverse proxy, but using https with a web server that doesn’t set the HTTPS environment variable, you can either set assume_secure_protocol=1 or reconfigure your web server.
For example, lighttpd should be configured with setenv.add-environment = ( "HTTPS" => "on" ). Similarly, nginx users should use something like fastcgi_param HTTPS on;.

I get the error Warning: Unexpected character in input: ‘\’ (ASCII=92) state=1

When you get an error message similar to Warning: Unexpected character in input: '\' (ASCII=92) state=1 this means that your PHP version is not high enough. See this FAQ for more information.

Why am I getting a warning about an untrusted hostname?

Most of the time this warning is displayed, just after you have just migrated Matomo (Piwik) to a new URL or server, and the new hostname you use will not be the same as the stored one. In this case, ask your Matomo Administrator to update the Matomo Hostname in Administration > General Settings.

(for geeks only) How does this message improve security?

This warning is a security feature Matomo provides to make Matomo more robust and prevent the so-called « Host Injection » vulnerability. Attackers could try to send fake hostnames to Matomo in an attempt to get users to reset their password through an attacker’s server. If users do that, the attacker could gain access to Matomo. Matomo protects against this type of attack by storing a list of trusted hostnames and checking if the ‘Host’ HTTP header in any request is in this list. If it doesn’t match, we show you a warning.

You can also disable the trusted host security check if for some reason you get this warning a lot, for example if you use Matomo with a changing set of hostnames. To do so,edit your config/config.ini.php and add the following below [General]

[General]
enable_trusted_host_check=0

This feature was developed as a « Security Best Practise », following a suggestion by a security researcher working with Matomo through our Security Research program.

When included in an IFrame, Matomo reports do not load. How do I allow Matomo reports to load from within an iframe?

By default, for security reasons, Matomo (Piwik) prevents standard pages and reports to be included in an iframe.
If you try to include Matomo pages as Iframe you will likely get the error Refused to display ‘https://example.com/’ in a frame because it set ‘X-Frame-Options’ to ‘deny’..

Use Widgets to embed Matomo in an iframe

To include your Matomo Analytics reports in your website or app or dashboard, using an iframe, we recommend you use the « Widgets » feature (Widgetize).

Not recommended: enable iframing Matomo app

The Widgets feature lets you embed in an iframe all Matomo reports. But sometimes you need to let your users also manage Matomo (for example, create new goals, funnels, dimensions, etc.) and you want to embed the Matomo app in an iframe. We don’t recommend embedding the whole Matomo app in an iframe for security reasons.

This is not recommended because:

  • it exposes your users to risks of Clickjacking
  • if you add a token_auth in the URL, it would then appear in server access logs, and this could include token_auth of admin or super users.
  • several people might be using the same « iframe » embed code with the same token_auth which would make it impossible to know who did what (since they’d all be logged in as the same user)

But if you really wish to go ahead knowing there are serious security risks, and when existing Widgets are not enough for your needs, you can edit your config/config.ini.php under the category [General] add the following line:

[General]
enable_framed_pages=1

If you also wish to enable the « Settings » pages (Manage websites, Users, etc.) to load in an iframe, you can also add the setting:

enable_framed_settings=1

And if you are using Matomo 4 or above, and want to be able to use token_auths of users with write or admin access with your iframe URLs, you will have to add the setting:

enable_framed_allow_write_admin_token_auth=1

Again, we don’t recommend using these settings, unless you absolutely need to and are aware of the risks.

See also: How do I enable users to login into Matomo inside an iframe?

How do I fix the error private directories are accessible?

In the Matomo System Report you may see an error that says « Required Private Directories » and looks like this:

This means the content for these files are accessible by anyone by entering the mentioned URL into the browser. Some of these URLs may include private information such as the credentials (username and password) to your database.

To fix these issues, your web server configuration needs to be adjusted. Please note this has nothing to do with file permission itself. This error needs to be solved either by a system administrator or you may need to contact your hoster.

Apache web server and IIS 7 and above

When you are using Apache, make sure your Apache configuration include "AllowOverride All".

If you are using Apache or IIS then these directories should be protected automatically. The only reason this might not work is if Matomo does not have write permission for these directories. In this case we recommend you try to execute below command in your Matomo directory using a user that has write permissions (if you can run commands on your webserver).

./console core:create-security-files

Please note that you may need to execute this command every time you update Matomo if Matomo is not allowed to create these files automatically.

Nginx web server

We recommend setting the same configuration as in our Nginx repository or directly using this repository to configure your Matomo installation.

Other web server

Configure your web server to not allow accessing any files in these directories:

  • /.git/
  • /core/
  • /config/
  • /lang/
  • /tmp/

I get the error: ERROR 1034 (HY000): Incorrect key file for table ‘matomo_log_visit’; try to repair it OR Table matomo_log_x is marked as crashed and last (automatic?) repair failed

When you get the error Table matomo_log_visit is marked as crashed and last (automatic?) repair failed. or ERROR 1034 (HY000): Incorrect key file for table 'piwik_log_visit'; try to repair it it means that the Mysql tables got partially corrupted and must be repaired. This problem may occur for various reasons (such as missing space on the disk) but it should occur very rarely.

It is possible to solve this problem by connecting to your MySQL server and executing the following queries:

REPAIR TABLE matomo_log_visit;

(replace matomo_log_visit with the name of your crashed table as it appears in the error message)

This may not work, in which case use the following solution:

cd /var/lib/mysql/your_matomo_database
myisamchk -r -v -f ./your_table_repair

Your tables should now be repaired and Matomo database up and running!

How do I reset the visualisations settings stored for a specific user, or for all users?

When you use Matomo (Piwik) and view the information displayed in any report, there are options you can use to configure how the data is displayed. For example you may change: the number of rows displayed in the report, the column being sorted, the visualisation being used (table, graph, treemap, etc.), etc. When a user changes one of these settings in any report, these settings are saved by Matomo so that the next time the user views this report, the report will be displayed as it was last configured by the user.

In some rare cases, you may want to reset these stored settings so that all of Matomo reports will be displayed with the default settings. For example, this is useful when the Visitor Log or Segmented Visitor Log fails to load for a user, often because the user had selected ‘all’ in the bottom-right dropdown, which may create performance issues on high traffic websites when Matomo tries to load thousands of visits in the log.

To reset the report settings for all users at once, run the following SQL query:

DELETE FROM matomo_option WHERE option_name LIKE "viewDataTableParameters_%";

To reset the report settings for a particular user my-username run the following SQL query:

DELETE FROM matomo_option WHERE option_name LIKE "viewDataTableParameters_my-username%";

What is the maximum URL length and how do I track my very long Page URLs and Page Titles without truncating them?

By default, Matomo (Piwik) will truncate Page URLs and Page Titles after 1024 characters (1 Kb).

If you are tracking Page Titles or Page URLs that are longer than 1024 characters, Matomo will truncate (cut off) the extra characters and also remove any additional URL parameters. To make sure that Matomo correctly tracks even your long Page Urls and Page titles, you can edit your config/config.ini.php and add the following:

[General]
page_maximum_length = 2048

After making the change, Matomo will track up to 2048 characters in your Page URLs and Page Titles. You may adjust the value appropriately for your use case.

As of Matomo 4.0.0, only the first 4096 characters of a page title or a page URL (and all action names) will be stored, even if page_maximum_length is set to a higher value. Referrer urls are generally truncated to 1024 but can be extended to 1500 characters using page_maximum_length.

I’m a developer, how do I enable logging (and / or SQL profiling) in Matomo?

There are a few possibilities with regards to debug logging in Matomo (Piwik).

  • Enable logging in the Tracker can be useful to debug Tracking issues or improvements. See the documentation page about enabling Debug logging in the piwik.php tracker
  • Enable logging in the Matomo UI: by default, Matomo logs messages in the UI (using notification boxes). If you want additional logging details, or if you want to enable logging to a file you can edit your config.ini.php and set the following options:

    [log]
    ; Possible values are "screen" (default value), "file", "database" (logs to tables logger_*),
    ; "errorlog" (logs using the error_log() php function) and "syslog" (logs to the syslog service)
    log_writers[] = file
    ; Possible values are ERROR, WARN, INFO, DEBUG
    log_level = WARN
    ; if configured to log to file, log entries will be written to this file
    logger_file_path = tmp/logs/matomo.log
    ; if configured to log to syslog, this is used as the identifier
    logger_syslog_ident = matomo
    

All logging configuration options can be found in config/global.ini.php

Important notes:

  • The Monolog Plugin must be activated in your Matomo server, you can check it by going to Administration > Plugins.
  • Once you have enabled logging, you can easily view & search the logs by using our LogViewer plugin: learn more in How do I view Matomo application logs?
  • You may also enable SQL logging & profiling to see the list of SQL queries executed by Matomo on any given page or widget. First, enable logging on screen (see point above). Then, edit your config.ini.php and add the following:

    [Debug]
    enable_sql_profiler = 1
    

Matomo will then output all SQL queries, group them by unique query, and show the total time spent as well as average time spent on each query.

Why do I see my page titles translated in a different language in the « Page titles » report?

In some cases a few page titles with very little page views may appear translated in the page title report even though none of your pages have such a title. A translated page title may be tracked under circumstances if you have visitors on your website that speak a different language and they use a specific translation feature within the browser.

What do I do when the browser tab becomes unresponsive when using Matomo?

Sometimes when viewing reports in Matomo your browser tab may become unresponsive.

For example in Firefox it may write A web page is slowing down your browser. What would you like to do? "Stop it" or "Wait". In Chrome it might say Page Unresponsive. "Exit pages" or "Wait".

This can happen when the report you are trying to view has too many rows and the browser loads too much data at once. This is likely caused by either selecting to view « all » rows or by selecting « make it flat » at the bottom of the report.

There are a few ways to stop this from happening:

  1. You can try to click « Wait » in the browser, and see if it succeeds after some time. (You may have to click « Wait » a few times.) If the page succeeds in loading, you can then revert the settings manually that caused the problems in the first place (for example, selecting to display « 10 » rows only and click « Make it hierarchical »).

  2. Or you can try loading the page on a faster computer and a modern browser, and then revert the settings manually that caused the problems in the first place.

  3. If you are only experiencing the issue viewing one of your website’s reports, then go to another website where loading the same report works, and change the settings there.

  4. Alternatively, and this solution will always work: you can reset the Matomo user settings for this specific user which experiences the issue, you can find the steps on how to reset the users settings in this FAQ.

When you experience this issue here is what it looks like in Firefox:

Or in Chrome:

How do I fix the error « This user has at least some write access. Only tokens of users who have only view access can be used. »

Since Matomo 4 you can embed widgets using an app specific auth token only if the user of that token has only view access. If the user has at least write (or admin or super user) access to one site, then this error will be shown and embedding the widget won’t work. This is to prevent accidentally using a token that could give other people enhanced permissions without you realising it.

To fix this error follow these steps:

  • create a new user and give this user only view access for the sites you want to embed reports for
  • log in as the newly created user
  • go to « Administration -> Security »
  • create a new app specific authentication token
  • copy the newly created token and use this token in the widget URL instead of the previous token

Matomo is slow after creating a custom report, funnel or installing users flow

Since Matomo 4 when creating new custom reports, historical data will be archived and old data will be made available for custom reports (as well as Funnels and User flows reports).

By default, the previous 6 months of data will be archived. This will happen either at the next archiving run or triggered by browser archiving. When using browser archiving, Matomo may become unresponsive while the reports are being processed. If you would like the historical data to be included, you should instead disable browser archiving and configure a crontab to run archiving, please see our guide here: configure automated archiving.

You may want to configure this feature to process more (or less) historical data. Configure the historical data by adding a new INI setting to set the number of months in your config/config.ini.php under the [General] section:

rearchive_reports_in_past_last_n_months = 3

You can also disable this feature by setting the setting to 0. Then only data from today onwards will be processed.

I get the error message: « Fatal error: Class ‘not found in … ». What’s wrong?

This issue is generally caused by missing files in your matomo/ directory. To fix this issue, please reupload all files from the latest Matomo version to your server.

If after re-uploading all the files from the latest version you still experience this issue, try to restart the web server.

If you still have the issue after doing those two steps, it may be a bug in Matomo. Please create a bug report.

How do I fix the error ‘Unable to find the wrapper « https » – did you forget to enable it when you configured PHP?’

To solve this error, you need to install the OpenSSL package for PHP on your webserver.

On a FreeBSD server, you may need to install the following package: php53_openssl and restart your webserver.

On a Windows server, open your php.ini config file and simply uncomment the following line:

;extension=php_openssl

and restart the webserver. The error should be resolved.

How do I disable the OPTIMIZE queries which take too long on my server?

When Matomo (Piwik) is setup to delete old logs, after the log deletion, we will run OPTIMIZE queries to claim the lost Mysql space on the database tables. These queries can be very slow to run and can cause problems on extremely large Matomo servers. If you see SQL queries and the server load going up out of control, with queries queueing because of an OPTIMIZE TABLE query, we recommend to disable all OPTIMIZE TABLE queries. To do so, edit config/config.ini.php and add:

[General]
enable_sql_optimize_queries=0

Note: Matomo will usually not OPTIMIZE tables which are Innodb tables (unless you are using MariaDB of version 10.1.1 or newer) but we will OPTIMIZE tables of the Myisam type.

How do I get LOAD DATA INFILE to work on my server?

Matomo processes huge amount of data and then stores this data in the database. For improved performance, Matomo tries to import a lot of data in the database at once using a Mysql feature called « LOAD DATA INFILE ». You can check whether your server supports this performance improvement in Administration > System Check menu. The system checks two commands: LOAD DATA INFILE and LOAD DATA LOCAL INFILE (which also works when the MySQL server is on a different server than your web server). It’s enough if either one of these work.

If you are not seeing a green tick under « Database abilities », try the following troubleshooting steps:

  • Check the « mysqld » process can access the file created in the tmp/assets directory in the matomo-installation:
    • give the process mysqld executable-access (+x) to files in path/to/matomo/tmp/assets/* and all parent folders.
    • check that the request isn’t blocked by apparmor or any other security-software when accessing this folder. If you are using Ubuntu, you may have to disable apparmor which prevents mysql from accessing files in path/to/matomo/tmp/*
      Edit the file /etc/apparmor.d/usr.sbin.mysqld and add the following path in the file: /path/to/matomo/tmp/assets/* rw,
      Then restart apparmor with sudo /etc/init.d/apparmor restart
    • in your Mysql configuration (my.cnf) set the following options: [mysqld] local-infile and [mysql] local-infile

Then restart Mysql.

If the LOAD DATA INFILE is still not working, try the following:

  • check in your config/config.ini.php that you do not have enable_load_data_infile=0. If you see this line in the file, delete it.
  • and/or update to the latest PHP version, or use the mysqli client (there are some known bugs with older PDO clients for mysql)
  • and/or switch the client to adapter=MYSQLI in the config/config.ini.php
  • and/or disable in your php configuration php.ini the options open_basedir and safe_mode. Restart webserver.
  • and/or if you are using PHP-Mysqli, you may have to enable the PHP setting mysqli.allow_local_infile = On
  • on Ubuntu / Debian servers, you may try to uninstall php5-mysql package and install instead php5-mysqlnd: sudo apt-get install php5-mysqlnd
  • on some systems you may also need to set secure_file_priv="" under [mysqld]
  • You can change the permission for your Mysql user to allow the user to import the files: GRANT FILE on *.* to matomo@localhost. Note it is generally not recommended for security reasons, and LOAD DATA LOCAL INFILE should work without this additional GRANT FILE permission.

If you still cannot make LOAD DATA INFILE work, you can disable this feature completely. This is not recommended for medium to high traffic Matomo where this feature should be enabled. To disable LOAD DATA INFILE add to your config.ini.php file under [General] section: enable_load_data_infile=0

How do I fix the problem of empty visits with « 0 action »?

In some cases, especially on a high traffic website, Matomo may show visits that have no pageviews or other actions listed, and the Visits log entry says « 0 action », and the Real-time report shows no actions for this visit. These « 0 action » visits may also be created in some rare cases when using Content Tracking.

If you experience this issue, it is likely because several Tracking API requests are sent and received at around the same time by the Matomo Tracking API server, and these concurrent requests somehow execute at the same time, and each of them may create a Visit. This is not expected but it can occur in edge cases.

This issue of « 0 action » visits may also occur if you’re using Heatmaps and you track a Heatmap on a page before you tracked a pageview with trackPageView.

How to workaround this issue?

  • If you’re using Heatmaps & Session recording, check that you are tracking a pageview on pages where you also track a Heatmap

  • If you use Content Tracking, or have a very high traffic website and you experience this issue regularly, you can reduce drastically how often these empty visit are generated by installing a new plugin: QueuedTracking. If you’re able to install and setup QueuedTracking then all requests for a given visitors will be queued and executed in a batch, likely resolving the issue.

How do I fix the error « General error: 3 Error writing file /tmp/xyz (Errcode: 28 – No space left on device) »?

When you’re getting the message « General error: 3 Error writing file /tmp/xyz » while using Matomo Analytics, the reason is that the disk space is full on your /tmp partition. The MySQL/MariaDB database is trying to create new files in the folder /tmp but the disk space is full, so we recommend to increase the size of the /tmp partition (or another path may be used as configured in your MySQL setting tmpdir).
Once you’ve increased the disk space of your tmp directory, your Matomo page should then load successfully.

Alternatively you may also get errors like « Got error 28 from storage engine » which means that one of the disks on which the MySQL databases are stored is full. To solve this issue, check which partition is full and then allocate more space to this partition. For example on Linux you can check which partition is full by running the command df -h.

How do I make sure Search engines robots do not index Matomo server?

To make sure search engines will not crawl any request to your Matomo (Piwik), create a file robots.txt at the root of your Matomo server with the following content:

User-agent: *
Disallow: /

How do I fix « curl_exec: Peer’s Certificate issuer is not recognized… Hostname requested was: plugins.matomo.org »

This message appears if you use a firewall or a proxy server that breaks SSL connections and re-encrypts them afterwards with its own certificate. Matomo uses a cacert file extracted from the Firefox browser and is therefore unable to connect to any SSL encrypted page with your specific setup.

To solve this issue, you are able to provide your own cacert file that trusts your proxies certificate. To use your own file, follow these steps:

  1. upload your cacert.pem file in a folder on your server such as /path/to/your/cacert.pem
  2. add custom_cacert_pem = "/path/to/your/cacert.pem" to the [General] section of your config file config/config.ini.php.
  3. Make sure the certification is readable by your webserver.

How do I fix the error ‘Fatal error: Maximum function nesting level of ‘100’ reached, aborting!’?

If you get the following error: Fatal error: Maximum function nesting level of '100' reached, aborting! in core:archive console output or in the Matomo (Piwik) UI, you can solve this problem by editing the Xdebug PHP extension settings in php.ini or xdebug.ini and add the following: xdebug.max_nesting_level=500. After making the change, restart your web server.

How do I fix if a timezone that doesn’t use the correct offset

Say you have selected the correct timezone for your location but the time is off by one hour. This may be due to an outdated timezone database version that doesn’t have for example the current daylight savings information for your location.

How do I find the version of the timezone database?

When using Matomo 4

A user with super user can easily find the version of the timezone database by going to Administration -> System Check. There you will find a row called « Timezone Version ». It might look something like « 2019.3 » meaning the timezone database is from 2019. In some cases the version might be reported as « 0.system ». That means your system uses the timezone database that was shipped with PHP.

Before Matomo 4

If you can access the command line on your server, you can get this information by executing the following command:

php -r "echo timezone_version_get();"

If your hoster provides a PHP Info then you can find this information in a row that says something like « Timezone Database Version » in the « date » section.

Alternatively you can also contact your hoster or system administrator and they may be able to provide this information.

How do I update the timezone database?

The easiest way is usually to upgrade your PHP version.

If this is not possible, you may need to install or update the pecl package timezonedb. How this is done varies depending on the operating system and hoster. If you don’t know how to do it you contact your hoster or system administrator.

How do I convert the MySQL database tables from MyIsam to InnoDB?

If you are upgrading from an old Matomo (Piwik) version (pre Matomo 2.1.0), you may be still using Myisam tables and getting errors such as « Waiting for table level lock ».

Such errors are occuring because your tables are not yet in InnoDB engine. You can convert your tables by using a specific SQL command. Note that the conversion of your big tables from Myisam to InnoDB will take some time and require a lot of RAM and space in the /tmp partition.

Run the following SQL query:

SET @DATABASE_NAME = 'name_of_your_matomo_db';

SELECT  CONCAT('ALTER TABLE `', table_name, '` ENGINE=InnoDB;') AS sql_statements
FROM    information_schema.tables AS tb
WHERE   table_schema = @DATABASE_NAME
AND     `ENGINE` = 'MyISAM'
AND     `TABLE_TYPE` = 'BASE TABLE'
ORDER BY table_name DESC;

Running this SQL query will generate a SQL ALTER statement which you can then execute to convert all your Matomo database tables from Myisam into InnoDB.

Copy paste the output of this SQL query and run this in your Matomo database and all your tables will be upgraded to InnoDB.

If your database is large, you may want first to temporarily enable the maintenance mode.

I get: PHP Fatal error Call to undefined function imagecreatefrompng()

If you get the error PHP Fatal error: Call to undefined function Matomo\\Plugins\\CoreAdminHome\\imagecreatefrompng() it means that you need to install the GD extension for PHP. The GD extension is required for Matomo (Piwik) to generate report graphs, generate sparklines graphs, as well as to upload a custom logo. To check whether the GD extension is installed on your server, go to Matomo > Administration > System Check.

How do I disable brute force authentication security checks for specific IP addresses?

When you are getting the message You are currently not allowed to log in because you had too many failed logins, try again later. it is because the Matomo brute force detection was triggered.

You can workaround this issue by whitelisting your IP address in Matomo > Administration > General Settings > Login, under the setting called « Never block these IPs from logging in ». If you enter your IP address in this field and then click Save, this will disable the brute force detector feature, and you shouldn’t get the error message « you are currently not allowed to log in » anymore.

For reference, here is what the Login settings look like:

Other options

If you cannot log in to make this change, try these things:

  • connect to your Matomo using a different network (for example using your phone’s data)
  • wait for an hour to be able to log in again
  • or temporarily allow your own IP through the config file by adding below config to your config/config.ini.php. Please note this will overwrite any previously configured IP in the UI:

[Login]
whitelisteBruteForceIps[] = "EnterYourIpAddress"

To find the cause of the Brute Force detection blocking an IP, please see our FAQ: How do I find the cause of the Brute Force detection blocking access from a specific IP?

How do I find the cause of the Brute Force detection blocking access from a specific IP?

If you’re getting the error message: You are currently not allowed to log in because you had too many failed logins, try again later.
The likely cause is failed login attempts via the Matomo Login page.

However, it may be helpful to determine which user (If any) caused a specific IP address to get blocked.
This can be done by checking the Activity Log in Matomo under Administration > Diagnostic > Activity log

However, the brute force detection can also be triggered by API requests with an incorrect or invalid token_auth
These failed requests will not be shown in the Activity Log, instead we will need to check the Matomo application log for further information.

First we need to make sure that logging is enabled: How do I enable logging in Matomo?

Next we can check our Matomo logs.
For example, failed API requests that subsequently trigger the Brute Force detection block will be shown in the logs as follows:

ERROR API[DATE TIME UTC] Uncaught exception in API: You can't access this resource as it requires 'view' access for the website id = 1. /path/to/matomo/core/Access.php:758
ERROR Matomo\ExceptionHandler[DATE TIME UTC] Uncaught exception: /path/to/matomo/core/Access.php/plugins/Login/Login.php(118): You are currently not allowed to log in because you had too many failed logins, try again later.
ERROR Matomo\ExceptionHandler[DATE TIME UTC] You are currently not allowed to log in because you had too many failed logins, try again later.

However, if these requests are being spaced out over time (For example one request every few minutes) then it may be more challenging to find the cause in the Matomo Logs.

The list of currently blocked IPs can be found in the Brute Force Log found in Administration > Diagnostic > Brute Force Log. There you will see a list of IPs that have been blocked and will be able to unblock them if necessary, for example:

However once the IP has been unblocked either through the Brute Force Log, the Login Settings menu, by adding the IP to the config.ini.php or by waiting for the block to be removed after some time it will be removed from this list.

If the IP is no longer showing in the Brute Force Log, we can then check the matomo_brute_force_log table in the Matomo database to see a list of failed login attempts. This can be done with the following SQL query:

SELECT * FROM matomo_brute_force_log;​​​​​

If you need to restore access from a blocked IP or to disable Brute Force detection, please see our FAQ here: How do I disable brute force authentication security checks for specific IP addresses?

Antivirus program or malware checker or Google Ads claim that matomo.js or piwik.js are malware, what can I do?

In rare occasions, it has happened that a particular Antivirus program maker, or a Malware detection tool, mistakenly claim that Matomo JavaScript tracking code is a malware.

When this happens, you may experience the following symptoms:

  • Visitor browsing the website(s) using Matomo may see messages from their antivirus or malware check tools for example `Malware was detected in the following file and it has been removed.`
  • Google Ads campaigns may be blocked and stop running and Google asking to remove the Matomo JavaScript tracking code.

As the Matomo creators, we guarantee that the original JavaScript tracker file does not have any malware.

When you’re experiencing this issue, please contact us to let us know about the issue. We will help you with the next steps.

How do I fix « SQLSTATE[HY000][2054] The server requested authentication method unknown to the client » error?

When setting up Matomo, if you’re facing an error « SQLSTATE[HY000][2054] The server requested authentication method unknown to the client », it is likely that you are using MySQL version 8.X. In MySQL 8.X, « caching_sha2_password » is the default authentication plugin (whereas in MySQL 5.7 and prior it used to be mysql_native_password »), which can cause some issues.

To solve this issue, do either one of the following:

1) Update your existing Matomo DB user and set the appropriate authentication type by executing the following SQL query:

UPDATE `mysql`.`user` 
SET `plugin` = 'mysql_native_password' 
WHERE (`Host` = 'YOUR MATOMO DB HOST NAME') 
and (`User` = 'YOUR MATOMO DB USER NAME');

or alternatively:

2) Create a new database and database user in MySQL by running the SQL queries from this FAQ, and then update your matomo/config/config.ini.php file to reference this new DB user.

Why do I have « 0 Action » visits in Matomo?

If you’re seeing a lot of « 0 Action » visits in your Visits Log, this indicates that the Matomo tracking code on your website or app is not tracking any « Pageviews » for these visits (But is tracking other actions such as impressions).

The reason for the « 0 Actions » visits may be for example media impressions (Such as images or videos) or form impressions when visitors visit a specific page on your website where you don’t have « Pageview » tracking setup.

This can be fixed by either adding the Pageview tracking code (_paq.push(['trackPageView']);) in the standard Matomo JavaScript tracker, or if you’re using Matomo Tag Manager by setting up Pageview tracking.

Alternatively, you can disable Form Analytics on specific forms (For example Login pages) by adding the data-matomo-ignore tag to your form.

How do I fix the issue « Response was ‘curl_exec: SSL certificate problem: unable to get local issuer certificate. Hostname requested was: » in the archiver?

When you setup auto archiving of your reports, you may find it fails to run with the following error: Response was 'curl_exec: SSL certificate problem: unable to get local issuer certificate. Hostname requested was: host.example

When you experience this issue, there are two solutions

  1. If possible, address the SSL certificate issue and get a SSL certificate for your domain name running Matomo. Then the core:archive script will be able to talk to Matomo over HTTPS without error.
  2. Or if for some reason you cannot, then you can edit your crontab and add the following parameter --accept-invalid-ssl-certificate to the core:archive command for example:

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

    Once the script knows to ignore the SSL certificate problem using this parameter, the error should be gone and the archiving script should hopefully proceed and succeed.

Why is the ‘url’ missing from some of the rows in data exports for Actions API?

By default, the Actions.getPageUrls API returns the same grouped/directory tree view as the pages report. If you want to get all pages and their URLs from the API, you can add &flat=1 to the API calls, which should then return all levels of the tree view as a flattened report. Every row in the API output will then also include the url value.

If you want to see a flat report in the Matomo Reports, click on the cog-icon below the report and click on « Make it flat ».

Does Matomo support the « View » feature similar to Google Analytics?

Matomo doesn’t offer the « View » feature that is found in Google Analytics.

In Google Analytics, the « View » feature is often to exclude internal traffic (from employees and colleagues) from being counted in the reports.

In Matomo, you can easily exclude data you don’t need before it gets to Matomo: learn more in this FAQ.

You may also create segments to filter out data you don’t want to see.

Why do the Matomo Page Performance report show some days with 0s Processing Time and others with very high processing time?

With Matomo 4, Page Performance tracking is included by default in the Matomo JavaScript tracking.
In some cases these reports will look quite different when comparing day to day reports with each other.

When viewing the Page Performance reports in Matomo you may even come across some days that show for example « 0s Avg. DOM Processing Time » for some days while other days show the same metric as very high (Eg. more than 8s for the same « Avg. DOM Processing Time ».

This can be caused by several different factors:

  1. Devices that have cached content loading the page quickly.
    Many browsers are able to very quickly or nearly instantaneously load content that has already been downloaded and processed. This is done automatically by many different browsers when it receives a « 304 Not Modified » response to a request.
  2. New content that is overriding cache-control attributes forcing a re-download and reprocessing of page content on some days.
    When your website was recently updated or new content was added, it may be expected that the processing time for this new content will be higher because the browsers may need to download updated content or scripts.
  3. Older devices which load the page a lot slower than others causing some days to have a much higher Avg. DOM Processing time.
    This is especially true for pages or websites that receive very little traffic. It is important to remember that the Avg. Performance metrics measured by Matomo can be heavily impacted by slow devices for low traffic pages and websites.
  4. Devices that do not support DOM processing Time or Network Time tracking.
    Unfortunately, not all devices support all of the tracking methods used for the Page Performance reports. When there is no data present for a specific performance metric, Matomo will show this metric as « 0 » in the reports.

How to make the diagnostic « Managing processes via CLI » to display Ok?

In Matomo Diagnostics, there is a check for « Setup Cron – Managing processes via CLI ». It is helpful to get this to work OK especially whenever you manage a high traffic Matomo instance or if there are a lot of websites or segments to be archived (learn more about improving Matomo performance).

For this diagnostic « Setup Cron – Managing processes via CLI » to work OK you need:

  • The following PHP functions must be enabled: shell_exec, getmypid (these are available by default in PHP but may have been disabled manually)
  • The system must provide the following commands: ps, awk (these are available by default in Linux systems)
  • The proc filesystem needs to be mounted at /proc for the ps x command to work (this is the default on linux systems)
  • The which package needs to be installed and working

Notes:

  • this is not supported on Windows
  • this is not supported on Synology devices
  • in some cases the configuration for web will have these functions disabled (For example if you have different INI files for CLI and web)

You can manually test if Managing processes via CLI is supported by running the following command in your server:

./console diagnostics:run --all | grep -i "processes via cli"

If it returns Setup Cron - Managing processes via CLI: INFORMATIONAL not supported (optional) learn more then it means that it is not supported yet (even on CLI). To troubleshoot why, and find out how to solve this issue, here are the following commands that should be running (from your terminal or SSH window as the Matomo user) for the diagnostic to display OK:

ps -e
# Should return a list containing PID, TTY, TIME and CMD for ps

awk -V
# Should return the installed version of awk, for example GNU Awk 4.2.1, API: 2.0

ls /proc
# Should return the full contents of the /proc folder

php -r "var_dump(function_exists('shell_exec'));"
php -r "var_dump(function_exists('getmypid'));"
# Should both return bool(true)

which
#should return nothing, if which is not installed it will return "command not found"
#in this case you will need to install the which package from your distributions repository

How can actions be lower across longer time periods?

You may have come across the scenario where a site you are monitoring has a higher number of actions in a month than what is displayed for the entire year for specific pages. This is likely due to the row limit when archiving, causing the page you’re checking to be added to the « Others » row.

To improve the performance of archiving the maximum rows are limited by default in the global config file, these are the default limits:

 ;during archiving, Matomo will limit the number of results recorded, for performance reasons
 ;maximum number of rows for any of the Referrers tables (keywords, search engines, campaigns, etc.)
 datatable_archiving_maximum_rows_referrers = 1000

 ;maximum number of rows for any of the Referrers subtable (search engines by keyword, keyword by campaign, etc.)
 datatable_archiving_maximum_rows_subtable_referrers = 50

 ;maximum number of rows for the Users report
 datatable_archiving_maximum_rows_userid_users = 50000

 ;maximum number of rows for the Custom Dimensions report
 datatable_archiving_maximum_rows_custom_dimensions = 1000

 ;maximum number of rows for the Custom Dimensions subtable reports
 datatable_archiving_maximum_rows_subtable_custom_dimensions = 1000

 ;maximum number of rows for any of the Actions tables (pages, downloads, outlinks)
 datatable_archiving_maximum_rows_actions = 500

 ;maximum number of rows for pages in categories (sub pages, when clicking on the + for a page category)
 ;note: should not exceed the display limit in Matomo\Actions\Controller::ACTIONS_REPORT_ROWS_DISPLAY
 ;because each subdirectory doesnt have paging at the bottom, so all data should be displayed if possible.
 datatable_archiving_maximum_rows_subtable_actions = 100

 ;maximum number of rows for the Site Search table
 datatable_archiving_maximum_rows_site_search = 500

 ;maximum number of rows for any of the Events tables (Categories, Actions, Names)
 datatable_archiving_maximum_rows_events = 500

 ;maximum number of rows for sub-tables of the Events tables (eg. for the subtables Categories>Actions or Categories>Names).
 datatable_archiving_maximum_rows_subtable_events = 500

 ;maximum number of rows for other tables (Providers, User settings configurations) 
 datatable_archiving_maximum_rows_standard = 500  

An example of where this may become an issue is if you have a page which is seasonal, visitors view it more in Summer than any other period of the year. The pageviews for the summer period will be high as that page is within the threshold of rows for that season. Across the year however that page is outside of the threshold so it’s results are added to the « Others » row in the yearly report.

You can increase the maximum row limit in your config.ini.php using the instructions in our FAQ and then invalidate the reports and process them again for the missing data to be included.

What is Paddle in relation to Matomo?

If you have a charge on your credit card statement from PADDLE.NET* MATOMO_ORG on your credit card, then you’ve recently made a purchase of the Matomo Analytics Cloud service by InnoCraft.

The Matomo Cloud order process is conducted by our online reseller Paddle.com. Paddle.com is the Merchant of Record for some of our orders. Paddle provides customer service inquiries and handles returns.

You can also find more information in InnoCraft.com Privacy Policy.

This can be caused a few different things either in the Matomo settings or in the setup on your website or web server.

  1. If all of the different websites are set in Matomo as the alias URLs then Matomo won’t track any of these as either outlinks or as referrers.
    If we take for example the following example websites: example1.com and example2.com

    If example2.com is added as a website in example1.com‘s settings in Matomo (See screenshot below) then any clicks on links from example1.com to example2.com won’t be tracked as outlinks:

    Likewise, if example2.com has example1.com set as a URL for itself, then any links clicked on from example1.com to example2.com won’t be counted as a referrer. For example if your settings for example2.com were as follows:

    As we can see from the tooltip in the Matomo settings for the websites (Administration > Websites/Measurables > Manage > Edit site), it specifies that any aliases added here will not appear in the Referrers > Websites report:

  2. If your website has links set with noreferrer, for example if using rel="noreferrer" then no referrer information will be sent to the website you are linking to. If you are using some other tool such as dereferer.org to strip any sensitive information from links between your website, then this can also cause no referrer information

  3. If your website has a redirect setup incorrectly (For example if you are linking to http and your website automatically redirects to https without forwarding the referrer information correctly) then its possible that there is no referrer information present when users are clicking on links between the websites.
    If this is the case, then it will be reflected in the Referrers > Websites report, as this would likely impact all referrer information for your websites.

    There is some additional information regarding this in our FAQ: Visits from search engines or campaigns are not recorded, Matomo shows “There is no data for this report” for all Referrers reports.

If this doesn’t help solve the issue, you can find additional relevant information in this FAQ: Matomo doesn’t track Downloads and clicks on Outlinks on my website.

How do I improve the load time of the find visitor SQL query when visitors have many visits?

You may notice a performance problem that a MySQL query like the one below causes a lot of load on your database. This can happen when a visitor has thousands of visits.

SELECT visit_last_action_time, visit_first_action_time, idvisitor, idvisit, user_id, visit_exit_idaction_url, visit_exit_idaction_name, visitor_returning, visitor_seconds_since_first, visitor_seconds_since_order, visitor_count_visits, visit_goal_buyer, location_country, location_region, location_city, location_latitude, location_longitude, referer_name, referer_keyword, referer_type, idsite, profilable, visit_entry_idaction_url, visit_total_actions, visit_total_interactions, visit_total_searches, referer_url, config_browser_name, config_client_type, config_device_brand, config_device_model, config_device_type, visit_total_events, visit_total_time, location_ip, location_browser_lang, campaign_content, campaign_group, campaign_id, campaign_keyword, campaign_medium, campaign_name, campaign_placement, campaign_source, last_idlink_va, custom_dimension_1, custom_dimension_2, custom_dimension_3, custom_dimension_4, custom_dimension_5, custom_dimension_6, custom_var_k1, custom_var_v1, custom_var_k2, custom_var_v2, custom_var_k3, custom_var_v3, custom_var_k4, custom_var_v4, custom_var_k5, custom_var_v5 
            FROM log_visit FORCE INDEX (index_idsite_idvisitor)  
            WHERE idsite = '1' AND visit_last_action_time <= '2020-12-07 20:34:48' AND idvisitor = '...'
            ORDER BY visit_last_action_time DESC
            LIMIT 1

If you are using the User ID feature feature, then a solution to fix this performance issue can be to adjust your config/config.ini.php and set below configuration option. Learn more about what this option does in How are requests with a User ID tracked?.

[Tracker]
enable_userid_overwrites_visitorid=0

If the User ID feature is not used or if you don’t want to change above configuration, it may help to adjust a database index using the two MySQL queries below (where the matomo_ DB table prefix needs to be adjusted depending on the configuration.). Please note that these queries can take a long time to execute and can slow down your Matomo while they aren’t finished. On a high traffic Matomo installation you may need to temporarily disable tracking until these two queries are finished.

DROP INDEX `index_idsite_idvisitor` ON matomo_log_visit;
CREATE INDEX `index_idsite_idvisitor` ON matomo_log_visit (idsite, idvisitor, visit_last_action_time DESC)

How do I report a bug in Matomo?

If you think you have found a bug, please read our guide on how to submit a bug report.

We appreciate if you take the time to report bugs that you experience with Matomo (Piwik). With your help, we will build the most reliable analytics platform!

Learn more about our Quality Assurance efforts.