I have an issue with the plugin, how do I troubleshoot and enable debug mode?

When you’re having issues with the plugin, we are happy to help and troubleshoot the issue.

First, you should always go to “Matomo Analytics => Diagnostics” (older versions have a menu item “Matomo Analytics => System Report”) to check if there is any error or warning. If the plugin doesn’t even install or crashes right away, you can still view the system report see further below. To help us troubleshoot your issue if there is no error in the system report, we need you to enable the debug mode (WP_DEBUG) in WordPress.

Enable debugging

To enable debugging, please edit wp-config.php file and add the following line:

 define( 'WP_DEBUG', true );

By default, the errors and warnings will be shown within the HTML pages (the other constant WP_DEBUG_DISPLAY is set to true by default). You can also choose to save all errors to a debug.log file inside the /wp-content/ directory, by adding the following line:

define( 'WP_DEBUG_LOG', true );

Learn more on the WP_DEBUG WordPress.org page.

If possible, we recommend also looking at your general PHP and webserver error log.

Get and copy the system report

In WordPress, go to the Admin panel, and under “Matomo Analytics”, click on “Diagnostics” (older versions have a menu item “System Report”).

Click the button “Copy system report” to copy the report to your clipboard.

Note: if you can’t even install the plugin at all, please update your wp-config.php file, and add the following line:

define( 'MATOMO_SAFE_MODE', true );

This will help making sure that the Matomo System report works even if you can’t install the plugin.

Click here for a detailed step by step FAQ on how to get the system report.

How do I disable all logging?

If you have WP_DEBUG always enabled and find Matomo for WordPress is logging not useful messages you can disable the logging of Matomo specific log messages by adding the following line in your wp-config.php (requires version 1.3.1 or newer):

define( 'MATOMO_DEBUG', false );

How do I log all messages?

If you want the plugin to log all messages (for debugging purposes), add the following line to your wp-config.php (requires version 1.3.1 or newer):

define( 'MATOMO_DEBUG', true );

Archiving and reports not working?

Check out this FAQ.

Matomo reporting, admin, or tag manager page not working?

Check out this FAQ.

Create an issue on Github and paste the System report

Next step is to create an issue in our Matomo for WordPress issue tracker. In the issue description, you can describe your issue in as many details as possible and then paste the System Report, as well as any error or warning messages.

Then disable debug mode again

Once you are done with troubleshooting, edit wp-config.php file and set the constant to false:

 define( 'WP_DEBUG', false );