Troubleshoot request errors after updating or installing Matomo On-Premise

Outdated or incomplete Matomo installations can sometimes lead to interface errors such as: “Oops, there was a problem with the request.”

The error may appear in the browser when Matomo’s backend cannot fully process the request, which could be caused by missing, outdated, or corrupted core files, or misconfigured server setups following an update. This guide outlines how to identify and resolve such issues in a self-hosted Matomo environment.

1. Check for missing or modified files

To detect whether your installation has any missing, outdated, or altered core files, run the built-in diagnostics tool from your Matomo root directory:

./console diagnostics:run`

If issues are found, you may need to refresh the installation with a clean set of core files.

If a manual upgrade was interrupted, Matomo may have updated the database schema without updating all application files. Run the following command to show if any pending updates need to be applied and ensure consistency between your files and database schema.

./console core:update 

2. Check for mismatched Matomo version files

Sometimes files from a previous or mixed version could remain after an update, especially if files weren’t fully overwritten. Run the following command and compare the output with the version in core/Version.php.

./console core:version

3. Reinstall core Matomo files (if needed)

If your diagnostics indicate that files are missing or corrupted, first back up your config and custom files (the files are found in matomo/config/config.ini.php, matomo/misc, and /matomo/misc/user).

Download the latest official Matomo release and extract the archive over your existing installation to ensure all core files are up to date.

You can then reapply correct file permissions to ensure all Matomo files are owned by the correct user. Note that permissions must not be too restrictive, for example, PHP must be able to read plugins, write to tmp/cache.

4. Clear outdated cache files after update

After replacing or updating files, clear the Matomo cache to avoid stale file references by running the following command:

./console cache:clear

Failing to clear the cache may result in broken interface elements or missing functionality.

5. Verify config.ini.php integrity

Although updates typically don’t overwrite your config/config.ini.php file, it’s worth checking the following (especially in multi-server or proxy setups):

• The file wasn’t modified or corrupted during an update.
• Required settings remain intact, especially if the update required manual intervention.

You can also compare your config file against a default install for completeness.

6. Check environment

File Synchronisation Across Servers

• For multi-node setups, check that all Matomo servers received the same updated files during the upgrade.
• Desynchronised plugin files, outdated caches, or incomplete deployments on some nodes can result in inconsistent behaviour and front-end errors.

If the issue isn’t related to an update or incomplete installation, refer to the guide on How to troubleshoot the error ‘Oops, there was a problem with the request’ to explore other possible causes.