Troubleshoot tracking issues with third-party integrations
While Matomo integrates with many third-party tools, we do not provide official support for third-party plugins and custom scripts. When an integration does not work as expected, follow these troubleshooting steps to identify and resolve the issue. If the problem persists, contact the third-party provider or the Matomo community for help.
1. Plugin compatibility and installation
First, verify that the plugin or integration is compatible with your version of Matomo and whether it is actively maintained by the developer. Outdated or unsupported plugins will cause issues. You can review the plugin details by clicking on the specific integration tile listed in the Matomo Marketplace or Matomo Integrations page.
Once you have confirmed that the integration is compatible and up-to-date, check that it has been correctly installed, activated, and configured according to the developer’s instructions.
2. Check for browser extensions or content blockers
When browser extensions such as ad blockers or script-blocking tools (e.g uBlock Origin) are enabled, they can prevent Matomo or third-party tracking scripts from loading. This can block tracking requests, cookies, or JavaScript files required for data collection.
Disable the extension temporarily or test in a private/incognito window with all extensions disabled to confirm if requests are being blocked.
3. Confirm script order
If the integration relies on the Matomo tracking code, the tracking script or tag must be correctly placed in your site’s source code. The tracking code needs to load before any third-party scripts to ensure proper execution. For example:
<head>
<!-- Other head elements such as meta tags and CSS -->
<!-- Matomo Tracking Code -->
<script>
var _paq = window._paq = window._paq || [];
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function() {
var u="//your-matomo-domain.example.com/";
_paq.push(['setTrackerUrl', u+'matomo.php']);
_paq.push(['setSiteId', '1']);
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
})();
</script>
<!-- Example third-party script that depends on Matomo -->
<script src="https://example-third-party-tool.js"></script>
</head>
Note: Some consent management platforms (CMPs) must initialise first to manage user consent before Matomo begins tracking. Always follow your consent manager’s implementation requirements to maintain compliance.
4. Check for network requests and console errors
Use your browser’s developer tools to check for script errors or blocked requests.
- In Chrome, Edge, or Firefox, press
F12(Windows/Linux) orCommand+Option+I(Mac). You can also right-click anywhere on the page and select Inspect or Inspect Element. - In the Console and Network tabs, look for blocked requests or JavaScript errors that may indicate where the integration is failing.
If requests to an external service fail, make sure the corresponding script or endpoint is reachable and not restricted by your site’s Content Security Policy (CSP) or by a consent management platform (CMP).
5. Verify the Matomo Tag Manager setup (if applicable)
If the integration is added through Matomo Tag Manager, use Preview / Debug mode to test how the tag behaves on your site. This lets you check that the tag fires at the right time, in the correct order, and that all required variables are populated as expected.
Also ensure that tag, trigger, and variable configurations are correct and that any consent requirements are met before the tag fires to prevent blocking or missing data.
6. Review server and error logs
For Matomo On-Premise:
- Review your web server and PHP error logs for entries related to the integration.
- Check both Apache or Nginx logs for configuration or permission issues that may prevent scripts from loading correctly.
- Analyse the Matomo system logs under Administration
> Diagnostic for warnings or errors that could indicate the cause of the problem.
7. Test in a clean environment
For Matomo On-Premise, try install Matomo in a clean test environment and enable only the core plugins and the third-party integration. This helps determine whether the issue originates from your configuration or another plugin conflict.
If testing in a separate environment is not feasible, temporarily deactivate non-essential plugins in your existing setup, clear the Matomo cache, and test the integration again. If the issue resolves after disabling a specific plugin, the problem is likely caused by a conflict that should be reported to the plugin developers.
8. Contact the integration developer
If the issue persists after completing the troubleshooting steps, contact the developer of the third-party plugin or integration. You can usually reach them by clicking the Learn More button on the plugin’s tile listed on the Matomo Marketplace page:
If the third-party tool is listed on the Matomo Integrations page, click the Download link to redirect to the provider’s website or GitHub repository:
When reporting the issue, include details such as your Matomo version, plugin version, PHP version, and hosting environment. It is recommended to describe the steps to reproduce the problem (in as much detail as possible) and attach any relevant console or log messages to help the developer identify the cause more efficiently.
9. Engage with community forums
If you are looking for peer assistance or advice, visit the Matomo Community Forums. Search through existing posts to determine if the issue has been discussed before; otherwise create a new post clearly describing your setup and the problem you are experiencing. Providing this information helps community members offer more accurate and effective guidance.