UPDATE: This tutorial was copied...
...to the official Mautic documentation: mautic.org/docs/en/tips/update-failed.html
Mautic dev team tests Mautic on different Mautic configuration and server settings, but sometimes, something causes an error. That is very unpleasant especially when upgrading Mautic to latest version, because it can cause Mautic to be in between of 2 versions and in many cases, that can make Mautic unusable. Here is a list of processes you can try to finish the upgrade manually.
The easiest is to look at
[your-mautic-url]/s/update/schema to see in what state your database is and to see if it applies the schema update. If it doesn't help or if Mautic is down completely, follow the next tips.
The process depends quite a lot if you have SSH access to the server where Mautic runs or not. Skip to the part "I don't have SSH access" if you don't.
I have SSH access
Good for you. That'll make things easier. Log in via command line and go to the directory where Mautic is installed. If you don't know how, search for a tutorial or contact the web/server hosting company to guide you.
Let's take it from the easiest fix to hardest.
1. Try to clear cache
When the upgrade failed in the last step, it's possible that only the cache is outdated. Try to clear it manually.
php app/console cache:clear
If this command throws a PHP error, you can try to nuke the cache folder like this:
rm -rf app/cache
If clearing cache didn't help, continue with next step.
2. Trigger update manually
Firstly, let's find out if there is some version to update to.
php app/console mautic:update:find
Output of this command should tell you clearly if there is a new version waiting to update to. If so, run:
php app/console mautic:update:apply
If there is no update to run, try next step.
3. Try to run database migrations
Let's check if there are any migrations to run.
php app/console doctrine:migration:status
If there are any, be sure you have backup of your database and then run:
php app/console doctrine:migration:migrate
4. See what changes between the entities (PHP code) and your database schema is
If the upgrade failed in the step of database update, this could solve it. Let's check if the database schema is up to date.
php app/console doctrine:schema:update --dump-sql
This will write all SQL queries that represent changes between the PHP entities and database schema. Do not execute them without understanding what they do. Especially if your database schema was created on Mautic 2 and your code base is on Mautic 3+. Upgrading database schema this way will not work as ID columns were changed from INT SIGNED to BIGINT UNSIGNED and all the foreign keys will not let the types to change.
5. Try to update files manually
There is no command for this. You'll have to:
- Backup (download) all Mautic files from your server to your local. You can use FTP or much faster scp command.
- Delete all Mautic files and folders. Use FTP or much faster rm command
- Download latest Mautic package from https://www.mautic.org/download/.
- Upload the zip package to the server, to the mautic folder. You can use FTP or much faster scp command.
- Unzip the package with
unzip 1.2.0.zip(change the zip file name). You can remove the zip file after (
- Upload app/config/local.php file from the backup on your local to the fresh Mautic on the server. (Mautic should run now)
- Upload your custom data if you have some. Custom files can be in folders: media/files, plugins, themes, translations.
I don't have SSH access
There is a PHP script which can do almost all steps from the section above. You can find it at
The description about how to make it work and use it is below the script. There are some details you'll have to do differently. For example you'll have to use FTP to download and upload files. You'll have to unzip on your local computer and upload unzipped files which will take a lot longer.
There is PHP error when I execute a command
Don't be afraid to read what it says. The best way how to deal with an error message is to copy the text and search for it with Google. You'll be able to find details about it and steps how to solve it. Here are examples of error messages and what to do when they occur:
Allowed memory size exhausted
PHP Fatal error: Allowed memory size of 67108864 bytes exhausted (tried to allocate 10924085 bytes) in ...
This can happen when the cache is being warmed up. It sais that Mautic needs more RAM to do it. It doesn't mean that your server hardware is rubbish. It means the Apache has the memory limit too low. Edit the
memory_limit in the php.ini configuration file.
A required PHP extension is missing
Fatal: Class 'ZipArchive' not found
This means that PHP cannot work with zip packages and it has to be installed first. Again, use Google to find solution.
I need help
If you are stuck and need help, that's fine. We've all been there. Let's ask someone for help. If you are sure you've discovered a bug and want to report it to developers, create a new issue at GitHub. If you think your configuration is causing the problem, ask at the forum. You can also chat with someone live in the Slack chat In all cases, describe the problem well. Here is what you should describe to get the problem solved fast:
- Steps to reproduce. Describe step by step tutorial how the problem can be reproduced.
- PHP version.
- Error messages. If you don't see the error message directly, search for it in the app/logs folder and in the server log. Server log can be find in different places. Ubuntu has it in /var/log/apache2/error.log file. Some web hostings provide an user interface to view the logs.
If you don't provide at least the above these information, the person who would like to help you will have to ask you for it. That’s a waste of your time and theirs. Also, please, be polite. Mautic is open source project and these people use their free time to help you.