How to Safely Upgrade Mautic from Version 4 to 5 - Complete Guide & Troubleshooting

5 min read

Keeping your Mautic instance up-to-date ensures access to new features, performance improvements, and security patches. The transition from Mautic 4 to Mautic 5, however, introduces some important changes. This guide will walk you through the upgrade process, including how to prepare, the steps to follow, and what to do if the update fails. 

Section 1: Preparing for the Update from Mautic 4 to Mautic 5

1. Backup Your Mautic Instance

Before any upgrade, take full backups to prevent data loss.

  • Database Backup: Use MySQLdump or phpMyAdmin to back up your database.
  • File Backup: Make a copy of your Mautic file system (themes, plugins, configurations, etc.).

2. Check System Requirements

Mautic 5 has specific requirements that must be met before upgrading.

  • PHP Version: Mautic 5 requires PHP 8.x. Confirm your PHP version using:
    php -v
  • MySQL/MariaDB Compatibility: Ensure your database meets the updated requirements for Mautic 5. Check the Mautic documentation for details.

3. Review Custom Plugins & Themes

Some customisations may break with the upgrade, so it’s essential to verify plugin and theme compatibility.

  • Custom Plugins: Check whether any third-party or custom plugins work with Mautic 5.
  • Replaced Plugins: The Citrix and Pipedrive plugins, previously built into Mautic, now require third-party replacements. Make sure to install and configure the appropriate replacements.
  • Email sending has also changed, so ensure you update your config area with the correct SMTP or updated plugin for your provider.

4. Move the Local Configuration File

Mautic 5 changes the location of the local.php file. Verify that the migration moves this file automatically from app/config/local.php to config/local.php. If not, move it manually.

5. Update Cron Jobs

Mautic 5 replaces certain cron job commands. The old command for sending emails via cron (bin/console mautic:emails:send) is now replaced by Symfony Messenger.

New Command

bin/console messenger:consume email

Review your cron jobs and update them to match the new structure. You can find the cron job documentation here.

Section 2: Step-by-Step Guide for Upgrading from Mautic 4 to Mautic 5

1. Perform the Upgrade via CLI

Upgrading via CLI is recommended for major version updates.

  • Step 1: Download the latest Mautic version from the official repository.
  • Step 2: Run the following commands to start the upgrade:
php bin/console mautic:update:apply

2. Apply Database Migrations

After upgrading, ensure that your database is fully updated by applying necessary migrations. You should run this command before an upgrade.

Command

php bin/console doctrine:migrations:migrate

3. Clear Cache

Clear the cache to avoid any inconsistencies with the new version.

Command

php bin/console cache:clear

4. Verify Cron Jobs and Email Transports

  • Test Cron Jobs: Ensure your cron jobs are functioning with the updated commands, especially those related to campaign triggers and segments.
  • Check Email Transports: If you use email service providers like Amazon SES, Sparkpost, or Omnivery, test to ensure they are functioning correctly after the update.

Section 3: Upgrading Within Mautic 5

For minor & major updates within Mautic 5 (e.g., from 5.1 to 5.2), the process should be conducted using the CLI. Refer to Step 2 above and follow the steps.

Section 4: Troubleshooting a Failed Mautic Update

If the update fails, follow these steps to resolve common issues using Doctrine commands.

1. Database Schema Mismatch

If your database is not fully updated to the new schema, you may encounter errors.

  • Error Example: SQLSTATE[42S22]: Column not found...
  • Solution: Apply the missing migrations to fix the schema:
php bin/console doctrine:migrations:migrate

2. Schema Not Updated Properly

If the schema wasn't fully updated, run the following command to synchronize it with Mautic 5: 

Command

php bin/console doctrine:schema:update --force

3. Issue with Custom Database Changes

If custom database changes were made and you need to restore the default schema, use the following command. Be cautious, as this will delete any custom fields or tables that don’t match the Mautic schema. (In future version the --complete will be removed)

Command

php bin/console doctrine:schema:update --force --complete

4. Reapplying Migrations

If your database is out of sync, you can reapply the migrations to ensure everything aligns properly.

Command

php bin/console doctrine:migrations:migrate

5. Red Error in Doctrine: Executed Unavailable Migrations

You may see a red warning indicating that some migrations are unavailable. This happens when a migration was applied, but its file cannot be found in the system.

  • Solution: Verify the migration files in app/migrations and make sure they correspond with the entries in the database migration table.

5. trigger_windowmissing in DB Migration

Upgrading to mautic 5.2.0 can results in the campaigns page causing an error 500. Follow this step.

  • Solution: Access your database and find the campaign_events table
    • Check if the column trigger_window is present
    • If not, add the column as
      • name: trigger_window
      • type: INIT
      • length: 11
      • default: NULL
      • Null: checked
    • Save
  • Clear cache and reload campaigns and the page should load.

Section 5: Last Resort: Forcibly Restoring the Database Schema

In severe cases, such as when custom database modifications are causing persistent issues, you may need to forcibly restore the Mautic database schema. This should only be done as a last resort.

1. Forcibly Update the Schema

This command will drop any custom fields or tables that don’t align with the Mautic schema, restoring the database to its default state.

Command

php bin/console doctrine:schema:update --force --complete

2. Reapply Migrations

After resetting the schema, reapply all necessary migrations to ensure the database is aligned with the latest version of Mautic.

Command

php bin/console doctrine:migrations:migrate

Further notes...

Upgrading from Mautic 4 to 5 is a critical step in ensuring your system remains secure and up-to-date. With proper preparation—especially backups, system requirement checks, and plugin verifications—the transition can be smooth. However, when issues arise, following the troubleshooting steps outlined here will help you get back on track.

Always test the upgrade in a staging environment before applying it to production, and keep backups on hand to avoid data loss.

Further Resources

Related post