Troubleshooting Failed Updates
There are a few things that can go wrong when updating Craft or installing/updating/removing plugins.
You may need to install Composer before running the composer commands listed in this guide.
Composer may not be able to find a compatible set of dependencies to install. #
When this happens, you’ll get an error like this:
Your requirements could not be resolved to an installable set of packages.
This can happen when you’re installing multiple plugins, which each rely on the same dependency, but at conflicting versions.
The full error message can be long and intimidating, but the good news is that it will have occurred before any changes were made to your site, so there’s nothing to recover from.
To get past the error, first go to your Craft project from your terminal, and run composer update.
If that command ends up giving you the same dependency conflict error, take a look at the full explanation, and let the plugin developers know about the conflict. If you need help understanding it, send an email to support@craftcms.com with the full error output, and attach your composer.json and composer.lock files.
A fatal PHP error can occur. #
If PHP runs out of memory, you’ll see something like this in the output:
Allowed memory size of 33554432 bytes exhausted (tried to allocate 100 bytes)
If PHP runs out of time, you’ll see something like this:
Maximum execution time of 30 seconds exceeded
To avoid these errors, edit your php.ini file and make sure that memory_limit is at least 256M, and max_execution_time is at least 120.
Generally these occur in the middle of a Composer update, which means that your vendor/ folder will be in a partially-updated state. To ensure that everything is fully updated, go to your Craft project in your terminal, and run composer update.
Once that’s done, you should be able to visit your Control Panel, run any new database migrations, and be on your way.
The gateway can time out. #
If you’re accessing your site through a gateway such as load balancer, Cloudflare, or AWS CloudFront, the gateway may be imposing its own time limit on requests, and could give up waiting for Craft to finish its update request.
Most gateways will let you configure the timeout duration. Like PHP, you should have it set to at least 120 seconds.
Cloudflare, though, has a non-configurable 100-second timeout. To work around it, Cloudflare suggests using a subdomain:
If you regularly run HTTP requests that take over 100 seconds to complete (for example large data exports), consider moving those long-running processes to a subdomain that is not proxied by Cloudflare.
See our How to Access the Control Panel from a Subdomain guide to learn how to do that.
A migration error can occur. #
Many updates come with new migration files, which are scripts that make changes to your database, project config, and other things. If something goes wrong in one of them, you will get an error that says:
One of Craft’s migrations failed.
(Or it may reference a plugin’s name instead.)
To get your site back up, first import the database backup that Craft saved in storage/backups/ before running the migration.
Database backup filenames will end in the Craft version number that was installed at the time, so if this occurred during a Craft update, you’re looking for a file that ends in the version of Craft you were updating to.
Then revert the changes made to your composer.json and composer.lock files.
If you’re running Craft 3.0.38 or 3.1.4 or later, you will find your previous composer.json and composer.lock files in storage/composer-backups/.
Otherwise, if you’re using Git, you should be able to do that by going to your project in your terminal and running these commands:
git checkout HEAD -- composer.json
git checkout HEAD -- composer.lock
Then go to your Craft project in your terminal and run composer install.
If you can’t revert the composer.json and composer.lock changes, just open composer.json in your favorite text editor, and manually edit the version constraints for craftcms/cms and any plugins you updated, back to the versions you were coming from. Then go to your project in your terminal and run composer update.
Once Composer is done installing the old vendor/ files, your site should be back up and running, as it was before the update.
Now zip up and send your storage/logs/ folder off to support@craftcms.com, or if you are sure a third party plugin was at fault, you can send it to the plugin’s developer instead.
Your CSRF token could be invalid. #
You might get this CSRF error updating Craft 3.7.20 or lower to 3.7.33 or higher from the control panel:
Unable to verify your data submission.
This looks like an update failure even though it most likely succeeded. Craft 3.7.33 changed the way CSRF tokens are generated, so all users are logged out during that update.
You should be able to refresh the page, log in, run any pending migrations, and confirm you’re on the new Craft version.