Fixing Matomo CLI Upgrade Errors After Failed Web Update to 5.6.1

ByPieter Bakker

When upgrading Matomo to version 5.6.1 via the web interface, the process fails if Composer is missing. Installing Composer and switching to CLI (console core:update) then triggers fatal PHP errors like Class 'Piwik\Plugin\Manager' not found in core/bootstrap.php:59. This happened to me on a production server with PHP 8.1.

Symptoms and Root Cause

Web upgrade to 5.6.1 fails with Composer errors. After installing Composer and running:

sudo -u www-data php /var/www/matomo/console core:update
PHP Fatal error:  Uncaught Error: Class "Piwik\Plugin\Manager" not found in /var/www/matomo/core/bootstrap.php:59

Cause: The web updater partially extracts files but leaves an inconsistent codebase. Composer dependencies aren’t fully resolved, and the autoloader can’t find core classes like Piwik\Plugin\Manager.

Step-by-Step Fix

1. Verify Current State

php -v  # Confirm PHP 8.1+ (required for Matomo 5.6.1)
ls /var/www/matomo/{core,vendor}  # Check for incomplete files
grep -i version_core /var/www/matomo/config/config.ini.php  # Note your DB version

2. Rebuild Composer Autoloader (Quick Fix)

cd /var/www/matomo
sudo -u www-data php composer.phar dump-autoload -o
sudo -u www-data php console core:update

Regenerates the classmap without touching database or config.

3. Clean Codebase Reinstall (Recommended – Keeps DB/Config)

cd /var/www
mv matomo matomo.old  # Backup current state
wget https://builds.matomo.org/matomo-5.6.1.zip
unzip matomo-5.6.1.zip
chown -R www-data:www-data matomo

# Restore config only
cp matomo.old/config/config.ini.php matomo/config/
chown www-data:www-data matomo/config/config.ini.php

4. Complete Database Update

sudo -u www-data php /var/www/matomo/console core:update --yes

Access the web UI to finish any remaining migrations.

5. Post-Fix Validation

# System check in Matomo UI
mysqldump -u root -p matomo > matomo-backup-$(date +%F).sql
curl "https://yourdomain.com/matomo.php?idsite=1&rec=1"  # Test tracking