This started life as a run of videos I made between 2021 and 2023, every time a new Magento release landed and I had to drag a pile of production stores up to it. I have rewritten the lot here into one piece, because the version numbers have moved on but the lesson has not. Upgrade day always begins with optimism. You read the release notes, you see the security fixes, you think this one will be clean. Then you point it at a real store with five years of history in it and the optimism evaporates.

Here is what I have learned about getting a Magento 2 upgrade through without taking the shop down with it.

Patch or upgrade? Answer that first

Before you touch composer, decide what you are actually doing. Magento gives you two roads: apply a security patch, or do a full version upgrade. The right choice comes down to two things, the client's budget and the complexity of the store.

An upgrade takes longer to apply, test and debug than a patch. If the store is heavily customised, full of third-party modules, or you did not build it and do not know where the bodies are buried, that time can balloon. In those cases I am honest with the client up front: we will put hours into the upgrade, and if it starts failing catastrophically and turning into a time black hole, we still have the security patch to fall back on. Naming that fallback before you start is what stops a bad upgrade becoming a bad week.

Everything through composer. No exceptions.

I have seen people try to upgrade by downloading a zip of the new version and piling the files into their install. It never goes well later, and it makes the next upgrade worse. Do the whole thing through composer. From 2.4 onwards the upgrade is driven by a composer require against the product metapackage, plus the upgrade compatibility plugin Adobe added to flag dependency conflicts for you. The exact commands shift between releases, so read the official upgrade docs for your target version rather than trusting a command you copied from a tutorial two years ago. The shape stays the same. The specifics do not.

Staging is not optional

Test the upgrade on a copy first. Always. A local or staging run on a recent dump of the production database is the only way to find the store-specific problems before your customers do. The point is not to watch it go through cleanly. The point is to hit the errors somewhere safe, work out the fix, and write it down, so that when you run it for real you are following a script instead of improvising while the site is in maintenance mode.

The classic trap: duplicate URL rewrites

The one that has bitten me hardest came in with 2.4.3, and the same shape of problem still turns up. The upgrade adds a constraint to the catalog URL rewrite tables, and setup:upgrade dies with a SQL error because those tables are full of duplicate entries that Magento never cared about until now. On an older store this is almost guaranteed. Redirects created, products deleted, categories renamed, years of normal trading leave duplicates behind in catalog_url_rewrite and url_rewrite.

Deleting the duplicate rows one at a time is a trap. On a busy catalogue there can be hundreds, and you cannot sit there doing it by hand while the site is down. What actually works:

• Put the site into maintenance mode. You are about to rebuild data the storefront depends on.
• Clear the two rewrite tables completely rather than picking at individual rows.
• Use a community "regenerate URL rewrites" tool to rebuild both tables cleanly, without the duplicates, so setup:upgrade can add its constraint.
• Then let the upgrade finish and check the storefront URLs resolve.

It is a genuinely risky operation, because on a large store you often have to do it against the production database. That is exactly why you rehearse it on staging first and time it, so the maintenance window is as short as you can make it.

Zend is gone, and it will tell you loudly

Around 2.4.3 Magento dropped Zend Framework and moved to Laminas. If you upgrade and then get Zend-related errors, often the first time you load the admin, the fix is to require the Laminas serializer and bridge packages through composer. You can do it before or after the upgrade. Once they are in, those particular errors clear. It is the sort of thing that looks terrifying in the logs and is a one-line fix once you know it.

It is almost never core. It is your store.

The thing nobody tells you early on: the PHP version bumps and the core upgrade are rarely what breaks. What breaks is the customisations, the third-party plugins, and how those plugins were installed by whoever came before you. A clean demo store upgrades in minutes. A real store that has been trading for years is a different animal, and the difference is entirely the stuff bolted onto the side. Knowing that changes how you scope the job. You are not testing whether Magento upgrades. You are testing whether this store upgrades.

The process I follow now

Back up first, both files and database. Run it on a staging copy. Work through every error and record the fix. Get the database into a clean enough state that the schema changes apply. Then, for the real run, put the site in maintenance mode, follow your own notes, and have the security patch ready as a fallback if the whole thing goes sideways. None of that is glamorous. All of it is what stops a Tuesday-night upgrade turning into an outage.

Honestly, doing this enough times is part of why I eventually moved away from Magento altogether. When upgrade day stops being a feature and starts being a recurring tax on your time, it is worth asking whether the platform is still earning its keep. I wrote about that decision in why I moved from Magento to headless. But while you are still running Magento, and plenty of good stores will be for years, do it through composer, rehearse it on staging, and never trust an upgrade you have not watched fail somewhere safe first.