Understanding Matomo Errors in Hurree

If you're experiencing issues with your Matomo widgets, this guide explains the most common errors and how to resolve them.

If you encounter an error that isn't covered below, please get in touch with our support team for assistance.

Explanation: Hurree could not authenticate with your Matomo installation. When connecting with an authentication token (token_auth), this can happen if the token is incorrect, has expired, or has been deleted, or if the associated user is no longer active. A temporary session token copied from an exported report may also stop working when the user logs out.

How to solve: Check your app-specific authentication token under Administration → Personal → Security in Matomo, then reconnect through Hurree with a valid token. Do not use a temporary session token from a report-export URL. Keep your token private. If the token appears valid but access still fails, please contact our support team; do not weaken your token's security restrictions without checking compatibility first.

Explanation: The Matomo user associated with the connection does not have the access needed for the requested report. Reporting access is controlled per website, so access to one site does not automatically grant access to another.

How to solve: Ask your Matomo administrator to confirm that the connected user has at least view access to the specific website referenced by your widget. Check that the widget uses the correct Site ID, then try again once access has been granted.

Explanation: The website, report, or segment referenced by your widget is unavailable, or the reference is incorrect. On a self-hosted installation, a changed Matomo URL or installation path can also prevent requests from reaching the expected API endpoint.

How to solve: Check that the website and report still exist in Matomo and that the widget references the correct Site ID. If your Matomo address has changed, review the connection details. Update the widget to use an active resource, or contact our support team if the reference appears correct.

Explanation: The request has been rate-limited by Matomo or the infrastructure hosting it. Applicable limits can differ between Matomo Cloud and self-hosted installations; a web server, proxy, or security service may impose its own restrictions.

How to solve: Wait before trying again and avoid repeated manual refreshes. If this happens regularly on a self-hosted installation, ask your hosting administrator to review request limits and server logs. For Matomo Cloud, check with Matomo support about applicable limits. Please contact our support team if you need help reviewing connector request volume.

Explanation: Matomo or its hosting environment could not complete the request. For Matomo Cloud, this may be a hosted-service interruption. For self-hosted Matomo, the cause may be in your own web server, PHP configuration, proxy, or hosting environment.

How to solve: Wait a moment and try again. For self-hosted Matomo, ask your administrator to check that the installation is accessible and review server and PHP logs. For Matomo Cloud, check for a service interruption. If the issue persists, please contact our support team with the exact error shown.

Explanation: Matomo or an intermediary did not respond within the time available. Large reporting requests or a busy self-hosted server can contribute to delays.

How to solve: Try a narrower date range or simpler reporting scope where available, then try again after a short delay. For self-hosted Matomo, ask your administrator to review server load if timeouts continue. Please contact our support team if the issue persists.

If you've completed the troubleshooting steps above and are still experiencing issues with your Matomo widgets, our support team is here to help.