Reproducing issues

• Try to reproduce the issue
  • Make sure to read and understand the user's issue fully before trying to reproduce the issue.
  • When trying to reproduce issues we currently usually reproduce the issue using the latest WordPress version which we have in our local install. If there is a critical issue we may also install the same version as the user's WordPress.
• Ask user for system report. If they are not comfortable sharing it publicly then they could email it to us to wordpress@matomo.org. For example:
• Hey @username, I can't reproduce the issue just yet. Could you share your [System Report](https://matomo.org/faq/wordpress/how-do-i-find-and-copy-the-system-report-in-matomo-for-wordpress/) with us? Either as a comment (the report is anonymised automatically) or alternatively by email to wordpress@matomo.org. If you send this by email please comment here afterwards just in case the email goes into the spam folder. We will then try to reproduce it using a similar set up.
• When we receive the system report check for any relevant errors/warnings or incompatible plugins etc.
  • If reports aren't showing up, check if visits were tracked in the last 5 days so we know whether tracking is failing or report generation. In system report category Matomo it should say Had visit in last 5 days: Yes if tracking is working.
  • If tracking is not working, check in system report if it is enabled.
    • If tracking is enabled and it is not working we can further troubleshoot the issue by asking for a URL to their website so we can see if the tracking code is embedded and whether everything looks fine. For example in browser developer tools we would check if a tracking request is sent to Matomo and whether an HTTP 200 or HTTP 204 is returned. Again we can ask users to either comment the URL to their website or to send it to us by email to wordpress@matomo.org.
    • If that is all looking good then we need to ask for access to the user's WordPress installation using the Matomo super user role (see further down how to ask for this). We can there in Matomo Analytics -> Settings temporarily enable the setting Tracker Debug Mode: Always Enabled. This way we can see for every tracking request the output and what exactly fails. Important is to disable it again afterwards.
  • If reports aren't showing up but tracking is working, then have a look at this FAQ: https://matomo.org/faq/wordpress/#matomo-for-wordpress-is-not-showing-any-statistics-not-archiving-how-do-i-fix-it
  • If they cannot access the admin or something is not working there check out this FAQ: https://matomo.org/faq/wordpress/i-cannot-open-backend-page-how-do-i-troubleshoot-it/
  • If ecommerce is not working, check
    • In system report under Matomo settings if ecommerce is enabled
    • In system report under Matomo settings if tracking is not disabled (as currently it won't execute ecommerce if tracking is disabled)
    • In system report under Matomo -> Logs check if there is any error for ajax_tracker in case server side tracking is failing
    • Try to reproduce the issue using a similar setup. You may need to view a product, then add to card and/or order the product. All these actions you should then see in WP Admin Dashboard -> Matomo Analytics -> Reporting -> Ecommerce -> Ecommerce log when you choose today in the date selector.
  • If there is a vendor issue then we can likely not fix the issue unless we fix https://github.com/matomo-org/matomo-for-wordpress/issues/233 and we might need to mark the plugin as incompatible or partially incompatible (see internal docs for this). A vendor issue is when another plugin embeds the same library but they use a different version that is not compatible with ours. They aren't always reproducible as it might depend on the order in which the plugins are loaded etc. It may be sometimes helpful to install the same plugins, and then search the plugins whether they embed the same library. Eg if the error is PHP Fatal error: Declaration of Symfony\Bridge\Monolog\Handler\ConsoleHandler::handle(array $record) must be compatible with Monolog\Handler\AbstractProcessingHandler::handle(array $record): bool in /var/www/html/wp-content/plugins/matomo/app/vendor/symfony/monolog-bridge/Symfony/Bridge/Monolog/Handler/ConsoleHandler.php on when we may want to search for ConsoleHandler across the entire WordPress installation including all the same plugins as the user has to maybe find if another plugin uses same dependency.
  • If our plugin breaks anything in the user's frontend (the actual website), this can have mostly 2 reasons:
    • Either our tracking code breaks something (this is unusual though unless they entered the Matomo tracking code manually -> Check in Matomo Analytics -> Settings if it's set to default tracking mode or manually. Also check the noscript tracking code which may be entered manually).
    • Or they have the matomo_opt_out shortcode embedded. We've had issues where this was not directly visible only after a click on privacy policy so we might want to search in the DOM inspector for matomo or opt out if this is somewhere embedded.
• To reproduce the issue you may need to enable the same plugins, to do this follow these steps:

  • If WordPress -> MultiSite is enabled on the user's install (see system report) then we may need to try and reproduce this issue in a MultiSite install

  • Install WP CLI see https://wp-cli.org/ (only needed once)

  • Get the list of the activated plugins from the Active Plugins row in the system report. Copy/paste the list of plugins.

  • Install the same plugins using WP CLI. wp plugin install --activate $pluginname1 $pluginname2 ...

    Example: wp plugin install --activate gravityforms advanced-custom-fields-nav-menu-field advanced-custom-fields-pro classic-editor

    You can use wp plugin deactivate and wp plugin deactivate --uninstall to deactivate/uninstall these plugins afterwards. Make sure you don't uninstall Matomo plugin otherwise all unpushed code changes will be lost! You need to remove the matomo plugin from the list of plugins. Please note that this does not install the same theme. Their theme is mentioned on the next row in the system report but they are usually not available on the WP plugins directory.

• Try to reproduce again

Some plugins won't be possible to be installed if they aren't on the WordPress plugins directory. If a plugin is not available on the WP plugins directory then we might not be able to reproduce the issue. For some plugins we may download a version from an official plugin website but only if the source is trusted. We never install plugins that we receive by email from users or customers as it is a security issue and could contain malicious code.

• If this doesn't help we may need to access the user's WordPress install. If we make changes in Matomo for WordPress settings remember any change you make and make sure to undo them once you're done troubleshooting. We never leave any changes without asking the user even if we could fix an issue. Like once a user had wrong tracking code in there but we would only change and correct it permanently after clarifying with the user. This is as we never know if something is maybe there on purpose eg re consent tools and it shows that we respect their site/install. Same goes for disabling plugins or changing other settings. Eg if we have to disable other plugins we would do it only for a very short time and make sure to do this only after having explicit permission for this.
• If we still cannot reproduce the issue, we need to ask the user to add a user for us on their WordPress for the email wordpress@matomo.org using the Matomo Super User role. Then we will only have access to the Matomo part in their WordPress but not anything else. For example we could say:
  • Hey @username. Unfortunately, we still can't reproduce the issue. Do you mind giving us access to your WordPress installation using the "Matomo Super User role"? This way we would have only access to the Matomo part in your WordPress but nothing else. If that's ok with you could you create this user for wordpress@matomo.org ? There's no need to email us the password as we would do a password reset. You'd need to send us by email the URL to your WordPress admin in order to know where we can log in. Once we're done troubleshooting you can remove the user again.
  • Please note that we usually aren't able to see the WP-Admin after logging in using this role. We need to access the pages once manually eg using $wpUrl/wp-admin/admin.php?page=matomo-settings or $wpUrl/wp-content/plugins/matomo/app/index.php.
  • Once completed and we don't need the login anymore we can let the user know that they can delete the account again.
• If we still cannot reproduce the issue or if we can't figure out what plugin or what is causing the issue then we may need to ask for administrator permission and we may need to temporarily disable some plugins to figure out which plugin is causing the issue. We could say something like
  • Hey @username. Unfortunately, we still aren't able to reproduce the issue|we still can't figure out what is causing the problem. Could you give our user administrator permission and would it be fine if we temporarily disable some plugins? We would make sure to undo any changed setting and it be only for a very short time.
• Rarely it may help to ask the user to create another user with the same role as their user in their WordPress and them checking themselves if they can reproduce the issue using a different user. This can be beneficial especially if they can't give us access to their WordPress. It's rarely the case though.
• If we still can't reproduce the issue there isn't much we can do. We could ask the user for the user's WordPress credentials and/or for access to the site's file or DB if needed. It was needed though so far.

Helpful links

• https://bethgsanders.com/basic-wordpress-troubleshooting/