I recently completed a full upgrade of a Mautic installation from version 4.4.2 to 6.0.4.
<script src="https://ams.mailertizer.com/focus/3.js" type="text/javascript" charset="utf-8" async="async"></script>It wasn’t exactly a “click and done” process — there were version compatibility issues, custom plugin conflicts, file permission problems, and a couple of performance hiccups along the way.
If you’re planning the same upgrade, here’s my step-by-step experience and what you should look out for.
Prerequisites
- A DigitalOcean Ubuntu 24.04 LTS server.
- A domain name pointing to your server (for production use).
- Basic understanding of Linux commands and SSH.
- At least 2GB of RAM on the server (or make swap memory – composer will timeout and fail otherwise)
Step 1: Update the Server
First, check for available updates:
php /var/www/mautic/bin/console mautic:update:find
The system showed 4.4.13 as the latest in the 4.x branch.
After running the update, I hit a “site broken” page due to this PHP warning:
2025/08/14 17:32:38 [error] 2441#2441: *36 FastCGI sent in stderr: "PHP message: PHP Warning: Undefined variable $inline in /var/www/mautic/offline.php on line 77" while reading response header from upstream, client: 99.98.97.96, server: mautic.upgrade.com, request: "GET /s/campaigns/1 HTTP/1.1", upstream: "fastcgi://unix:/run/php/php8.0-fpm.sock:", host: "mautic.upgrade.com", referrer: "https://mautic.upgrade.com/s/login"
Fix:
A quick cache clear resolved the issue:
php /var/www/mautic/bin/console cache:clear
Step 2 – Preparing for the 5.x Upgrade
Running the update check again showed:
php /var/www/mautic/bin/console mautic:update:find
Version 5.2.7 of Mautic is available for download. Please visit https://github.com/mautic/mautic/releases/tag/5.2.7 for more information.
To update, you can run 'php bin/console mautic:update:apply' from the command line.
php /var/www/mautic/bin/console mautic:update:apply
Are you sure you wish to update Mautic to the latest version? yes
Step 1 [>---------------------------] Running pre-update checks...
But the upgrade failed with:
One or more errors occurred while checking your environment prior to updating Mautic:
- Your PHP version is too old or too new for Mautic to update. You are currently running PHP 8.0.30. Please make sure that your version is between 8.1.0 and 8.3.99.
That error’s pretty clear — Mautic won’t let you update while you’re on PHP 8.0.30 because it now requires PHP 8.1–8.3.
You’ll need to:
1. Install a newer PHP version (8.1.x, 8.2.x, or 8.3.x — I’d recommend 8.2 for stability unless you specifically need 8.3).
2. Switch the CLI and web server to use that PHP version.
3. Rerun the update.
Upgrade PHP to 8.2
On Ubuntu with Nginx + PHP-FPM:
sudo add-apt-repository ppa:ondrej/php
sudo apt update
sudo apt install php8.2 php8.2-cli php8.2-fpm php8.2-common php8.2-mysql php8.2-xml php8.2-mbstring php8.2-curl php8.2-zip php8.2-intl php8.2-gd
sudo update-alternatives --set php /usr/bin/php8.2
Update your Nginx PHP-FPM config to use php8.2-fpm, then restart:
sudo systemctl restart php8.2-fpm
sudo systemctl restart nginx
Switch Nginx PHP-FPM pool to 8.2
Edit your Nginx site config:
sed -i "s/8.0/8.2/g" /etc/nginx/conf.d/mautic.conf
root@mautic-upgrade:~# nginx -t
nginx: [warn] "ssl_stapling" ignored, no OCSP responder URL in the certificate "/etc/letsencrypt/live/mautic.upgrade.com/fullchain.pem"
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
root@mautic-upgrade:~# systemctl restart nginx
sudo systemctl restart php8.2-fpm
root@mautic-upgrade:~# sudo systemctl restart nginx
Step 3 – Upgrade to 5.2.7
With PHP 8.2 ready:
php /var/www/mautic/bin/console mautic:update:apply
php /var/www/mautic/bin/console mautic:update:apply --finish
Plugin Compatibility Issues
At this stage i started running into compatibility problems with custom plugins i had installed:
A custom plugin (MauticMultiDomainBundle) broke the upgrade.
I moved incompatible plugins out of /plugins: (Probably any plugin you had that was a custom plugin you will need to move out of the plugin directory.)
mkdir /root/Mautic4Plugins/
mv MauticMultiDomainBundle/ /root/Mautic4Plugins/
mv ExtendedSegmentsBundle /root/Mautic4Plugins/
Then re-ran the upgrade.
File Permission Fix
At this stage on a site refresh the site did not load:
The site is currently offline due to encountering an error. If the problem persists, please contact the system administrator.
==> /var/log/nginx/mautic.access <==
99.98.97.96 - - [14/Aug/2025:17:42:53 +0000] "GET /s/campaigns/1 HTTP/1.1" 500 1325 "https://mautic.upgrade.com/s/login" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36"
==> /var/log/nginx/mautic.error <==
2025/08/14 17:42:54 [error] 14497#14497: *6 access forbidden by rule, client: 99.98.97.96, server: mautic.upgrade.com, request: "GET /app/assets/fonts/source-sans-3-v15-cyrillic_cyrillic-ext_greek_greek-ext_latin_latin-ext_vietnamese-regular.woff2 HTTP/1.1", host: "mautic.upgrade.com", referrer: "https://mautic.upgrade.com/media/css/app.css"
==> /var/log/nginx/mautic.access <==
99.98.97.96 - - [14/Aug/2025:17:42:54 +0000] "GET /app/assets/fonts/source-sans-3-v15-cyrillic_cyrillic-ext_greek_greek-ext_latin_latin-ext_vietnamese-regular.woff2 HTTP/1.1" 403 196 "https://mautic.upgrade.com/media/css/app.css" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36"
==> /var/log/nginx/mautic.error <==
2025/08/14 17:42:54 [error] 14497#14497: *6 access forbidden by rule, client: 176.231.132.234, server: mautic.upgrade.com, request: "GET /app/assets/images/favicon.ico HTTP/1.1", host: "mautic.upgrade.com", referrer: "https://mautic.upgrade.com/s/campaigns/1"
==> /var/log/nginx/mautic.access <==
99.98.97.96 - - [14/Aug/2025:17:42:54 +0000] "GET /app/assets/images/favicon.ico HTTP/1.1" 403 196 "https://mautic.upgrade.com/s/campaigns/1" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36"
At this stage i cleared the cache but yet still getting error and site not loading ☹️
99.98.97.96 - - [14/Aug/2025:17:43:52 +0000] "GET /s/login HTTP/1.1" 500 1325 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36"
==> /var/log/nginx/mautic.error <==
2025/08/14 17:43:52 [error] 14497#14497: *18 access forbidden by rule, client: 99.98.97.96, server: mautic.upgrade.com, request: "GET /app/assets/fonts/source-sans-3-v15-cyrillic_cyrillic-ext_greek_greek-ext_latin_latin-ext_vietnamese-regular.woff2 HTTP/1.1", host: "mautic.upgrade.com", referrer: "https://mautic.upgrade.com/media/css/app.css"
==> /var/log/nginx/mautic.access <==
99.98.97.96 - - [14/Aug/2025:17:43:52 +0000] "GET /app/assets/fonts/source-sans-3-v15-cyrillic_cyrillic-ext_greek_greek-ext_latin_latin-ext_vietnamese-regular.woff2 HTTP/1.1" 403 196 "https://mautic.upgrade.com/media/css/app.css" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36"
==> /var/log/nginx/mautic.error <==
2025/08/14 17:43:52 [error] 14497#14497: *18 access forbidden by rule, client: 99.98.97.96, server: mautic.upgrade.com, request: "GET /app/assets/images/favicon.ico HTTP/1.1", host: "mautic.upgrade.com", referrer: "https://mautic.upgrade.com/s/login"
==> /var/log/nginx/mautic.access <==
176.231.132.234 - - [14/Aug/2025:17:43:52 +0000] "GET /app/assets/images/favicon.ico HTTP/1.1" 403 196 "https://mautic.upgrade.com/s/login" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36"
Some files were owned by root instead of www-data. Fixed with:
sudo chown -R www-data:www-data /var/www/mautic
php /var/www/mautic/bin/console cache:clear
5.2.7 was now running perfectly. Just as a precaution I made a snapshot so i have a working version of 5.2.7.
Also should be noted that your email configuration and mautic whitelabeller will stop working and will require new configuration.
Step 4 – Upgrade to 6.0.4
php bin/console mautic:update:find
Then run:
php bin/console mautic:update:apply --finish
Now this is taking a loooong time…..
mauti-upgrade:/var/www/mautic# php bin/console mautic:update:apply --finish
Step 1 [>---------------------------] Migrating database schema…
Then got this:
An error occurred while updating the database. Check log for more details.
So i did some digging and found out that mysql had gone away, so restarted the service and also provided some more swap memory just in case, might need more memory actually running a pretty slow server
php /var/www/mautic/bin/console mautic:update:apply --finish -vvv
Step 5 – Final Cache Clear
After upgrade, the site had “Access Forbidden” errors for fonts/images.
Clearing cache fixed it:
php /var/www/mautic/bin/console cache:clear
And just like that Mautic 6.0.4 is up and running!!!
But remember no email sending and no whitelaballer
At this stage i hit a hiccup if you want to install symphony/sendgrip, you will have to have composer installed and it is highly recommended that you use composer to install mautic 6!
So we will have to see if we can do that and then migrate the database to the new serve
Ok so now you should have Mautic 6.0.4 running, there are some issues, we did this via the command line and not using composer which makes an issue for installing other stuff you might need like sendgrid api which you will need composer for.
So what i did at this stage was take a mysqldump of my current DB, went and did a clean server install and a clean install of Mautic 6, imported my database and started from there. But that will be another blog post…..
