How to Downgrade Mautic

Troubleshooting Mautic Update Issues

Hopefully this doesn’t come up often, but sometimes you need to roll back Mautic to a previous version. Whether it’s a plugin you found out was incompatible, or a functionality change that impacts your established processes, it’s always helpful to know that you can (unofficially) downgrade Mautic to get temporary relief.

Please note: This process is not applicable to crashed Mautic instances, such as ones that were interrupted during the upgrade process. For help recovering from a bad upgrade, see our guide here or contact a Mautic consultant to discuss your options. The instructions below are for those who successfully upgraded their Mautic instance, but “don’t like” it for a particular reason.

Option 1 – Restore from a Backup, both Mautic Files and Database

If you had a previously working Mautic installation, the most straight forward way to downgrade it is to restore a backup. This backup should consist of all the files in your Mautic directory, in addition to a dump of the database (typically provided as a .sql file). The process to retrieve and restore an earlier backup will depend on your hosting environment and how you handle your backups.

Common backup tools installed on web hosting providers’ servers include cPanel Backup, R1Soft Continuous Data Protection and/or CodeGuard Backups. Depending on the backup implementation, you may need to download a full backup of your entire hosting account then extract the folder containing your Mautic files.

The major downside of restoring a backup to downgrade Mautic, is that you’ll lose any settings, contact data and assets that were inserted since the backup was taken. This may or may not be acceptable to you depending on a) how often you perform backups b) how many changes happened to your Mautic instance since then.

Option 2 – Download Fresh Installation Files Only

Do you suspect your Mautic problems are being caused by a bug in the latest release? If you want to downgrade to a previous version but can’t afford to lose the most recent info in your database, this approach might be for you. Typically, this option is only recommended if you are downgrading to the previous one or two releases. Anything older than that is likely to have significant structural changes in the database that will cause the downgrade to fail.

Backup your current Mautic installation
Before you begin, copy your current Mautic installation over to a separate folder and perform a full export of your MySQL data to a SQL file — View instructions here. Store these backups in a safe place; ideally download them to your local hard drive. In case downgrading doesn’t resolve your issue, you will need these files to get back on the latest version.

Copy your local.php file and user data directories to a separate folder.

Before you delete your Mautic installation, ensure you have the full backup above, then copy the following files and directories to a separate folder (above your Mautic directory) on your server. /path/to/mautic is a placeholder for the directory where your Mautic installation resides. For cPanel users, it may begin with /home/username/public_html/. For dedicated/VPS server users, it might be /var/www/html/ instead. Check with your administrator if unsure.

/path/to/mautic/app/config/local.php
/path/to/mautic/media
/path/to/mautic/themes
/path/to/mautic/plugins

Tip: Unless you have any plugins installed that were not bundled with Mautic, it’s preferable to omit the /plugins directory and let Mautic’s installation file overwrite them with the plugin corresponding to the core version you are downgrading to.

Download the version of Mautic you would like to downgrade to.

Download & extract the version of Mautic you would like to downgrade to your Mautic folder. You may downlaod any version of Mautic at the following URL:  https://s3.amazonaws.com/mautic/releases/${MAUTIC_VERSION}.zip, where ${MAUTIC_VERSION} is the version number formatted like this: 1.1.1.

If you have shell access, it’s faster to wget and unzip to download the file directly to your server, then expand it.

Copy local.php and user data back into your downgraded instance.

Before the downgraded instance is able to communicate with your existing database, you need to copy local.php back into the /path/to/mautic/app/config/ directory. Otherwise, visiting your Mautic URL will prompt you to reinstall Mautic with new settings, repopulating your database with default data.

Copy your personalized /media, /themes and /plugins folders back into your Mautic folder and overwrite any files to prevent losing your theme customizations, images, downloadable assets and third-party plugins.

Set permissions and ownership on your Mautic files.

Like any new Mautic installation, you should set the correct permissions on the directories and files, especially the /app, /media, and /translations folders. Recursively set these folders as 755 using your FTP client, or the chmod -R 755 /folder_name command in a terminal.

In addition, the user running your web server process should be the owner of all your Mautic files. Usually this is www-data:www-data or apache:apache, but may be configured differently on your server. Again set this privilege through your FTP client, or if the shell is more your speed, use chown -R /path/to/mautic.

Try logging in to your downgraded instance.

Visit your Mautic login page and try accessing your dashboard to ensure the downgrade has proceeded successfully. Now is a good time to check whether your user-defined plugins, themes and media files have transferred over successfully. It’s also good practice to test whether any connectors, such as WP-Mautic or Salesforce CRM sync are still functioning as intended. If you’ve come this far with no problems, you’ve probably downgraded Mautic successfully.

To save yourself time & headaches in the future, it’s advisable to do a full backup of your Mautic files and database immediately before an update, so you can roll back more easily to your latest data, if needed.