Divi 4 to Divi 5 Migration

We worked as the technical experts to help a client through a complicated WordPress Divi Theme update with no downtime.

About the Client

The client was Core Business Solutions, my former employer. Their site was and always has been built on WordPress and uses the Divi theme. Personally, I am not a fan of Divi.

But I have to admit: the combination of WordPress and Divi did a decent job at letting the marketing team build and maintain the website independent of too much technical assistance.

The Problem

The site was on Divi 4, which is the previous major version of the theme. While it didn’t need an immediate upgrade, there were reasons to do so:

  • The site has always had performance issues (did I mention I’m not a fan of Divi?)
  • The Divi 5 upgrade boasts performance improvements
  • Divi 4 falls out of support in a few months, so security would force an upgrade

The marketing team generally handles their own upgrades but used me, the resident WordPress expert, as a backstop when they run into issues. Past experience told them a major Divi upgrade was going to be a challenge, so they called me in.

The upgrade was a challenge, and there were several technical issues that we ran into and resolved along the way, which I’ll describe in the next section.

The Job

On the surface the job was simple:

  • Upgrade the site’s Divi theme from 4 to 5
  • Make sure it didn’t break anything
  • Make sure all pages render more or less the same as they did before.

Under the surface, this job became a complex, time-consuming process.

The Solution

The solution includes several important parts:

  • Backup the production version of the site.
  • Use the backup to create a staging version of the site.
  • Use the staging version to perform and validate the updates.
  • Use both tools and manual checks to validate the success of the updates.

We got there successfully and the client was satisfied. The process was not straightforward, and I’ve included the details below if you’re interested.

The Details

If you’ve got a Divi 5 upgrade to do and it’s running into issues, I’ve included the details of this project below in case it helps.

Use a Staging Site for the Upgrade

I began by using the Staging Site feature of their hosting environment to make a copy of the production site and process the upgrade. In my opinion, this is table stakes when it comes to managing a WordPress website for any client that can afford a white-glove approach to their hosting and maintenance.

Processing updates on a staging site allows you to validate that the updates don’t break anything before setting them loose on your live site.

Processing the Theme Update

The simple act of clicking “Update” in WordPress went fine. But when migrating from Divi 4 to Divi 5, that doesn’t actually do much.

Divi 4 and Divi 5 basically have separate backend engines and the full upgrade path requires you to run a migration tool that safely migrates content to the Divi 5 format. Until you do that, Divi 5 basically renders your content using the Divi 4 engine.

In other words: the theme upgrade itself won’t break your Divi 4 content, but it will still render with Divi 4 code and not benefit from the performance improvements.

Unfortunately when I ran the migration tool, it did not detect and upgrade most of our content, and I needed to do some lower-level troubleshooting to find out why.

Troubleshooting the Migration Tool

The migration tool gives a count of all of the content and modules it detects and upgrades. The numbers were ridiculously low, and it was clear it was not finding everything.

Tip for Divi: Silent Failure Sucks

If I didn’t know better, everything looked fine. It gave me a content count, and it upgraded what it could find. But I knew better.

I opened my browser’s dev console and watched what was happening. When the migrator did its job, it fired a series of admin-ajax.php calls to WordPress’s backend. It seemed as though the purpose of this job was to get a count of all posts of every possible post type in the database.

Some of these requests failed. But the frontend didn’t show the failure.

As the person handling the technical issues for this site, it would have been nice if Divi had given some hint that something was wrong rather than just pretending my site had no content to migrate. I shouldn’t have to watch the Dev Console’s Network tab to know something went wrong.

Identifying Why it Failed

The requests were not returning an HTTP status code, or a response body. They literally told me nothing. That’s pretty unusual for WordPress to do on its own but pretty typical when something is going on at the PHP or web server level. I enabled WP_DEBUG, tried the migration again, and watched.

To nobody’s surprise, PHP died because it ran out of memory. This happens when a PHP script needs more memory than PHP is configured to allow via the memory_limit configuration option.

Dealing With the Memory Limit Issues

We’re in a managed hosting environment. I can’t change that myself. So, I asked support to do it. The initial memory limit was ridiculously low, which annoyed me given how much I know we pay for hosting. They increased it several times. Each time the migration went further, but eventually failed. When we hit 1 GB of memory and it was still failing, they refused to go higher.

I don’t blame them, honestly. I didn’t dig further but I suspect, Divi’s migrator is doing something incredibly irresponsible in terms of writing memory efficient code. When I see this sort of thing happen, it’s usually because someone wrote a SQL query that doesn’t account for large data sets, and so it doesn’t do any paging. The code selects all the data from a table at once, then operates on all of it in memory at once. Again, it’s just a theory.

In reality, this left me “stuck” because the host wouldn’t increase the memory limit to a point where I could process the upgrade.

The Way Out: Do it Locally

So instead, I used LocalWP and checked the staging version of the site out locally, where I could change PHP’s config myself. The process was:

  • Check out the site
  • Change the memory_limit in php.ini for the site to 2GB, and restart the site.
  • Use the Divi 5 Migration Tool, watch dev console for failures

With gobs of memory to waste, the Migration Tool succeeded on the first pass. But that didn’t mean I was done.

Cleaning Up Unmigrated Content

After the Divi 5 upgrade, any page that has components that were not automatically migrated will show a Backwards Compatibility warning when you view them from a logged-in session. Several pages were reporting this.

I did what people do these days: I pointed Claude at the page and asked for help. It determined that I had code blocks that were not migrated because they had settings that were removed and did not have a fallback. It recommended we just run a search/replace on the database to eliminate the settings from those blocks. I backed-up the database, and then I let it rip.

It worked.

(That probably would have taken me hours on my own. Instead it took minutes. Cool.)

Once I got to this point, I pushed the updated site back up to the staging environment, so the marketing team could help me proof it.

Review and Cleanup

At this stage I used a combination of tools to find issues, as well as the institutional knowledge of the marketing team and their keen eyes to manually check things. There were two classes of issues:

  • Issues caused by LocalWP and Flywheel not doing a great job of rewriting URLs. We had images that failed to load due to CSP Policies that prevented loading images via http:// on our https:// site. And we had fonts that were still trying to load from http://localhost which wasn’t going to work out.
  • If you have a Divi website long enough, you’re going to end up with some custom CSS implemented to dial things in just the way you want them. Or, you’re going to have content where you’ve screwed around with the settings until it looks the way you want it to look, but you don’t really understand why.
The URL Issues

Solved by a search/replace. I use the Better Search Replace plugin for these kinds of operations.

The Divi Upgrade Slop

I’m actually impressed by how little the Divi update and migration breaks anything. At least, when you’re more or less accepting the out of box experience and not dialing things in too much.

But once you do, all bets are kind of off. We had a number of these situations. I’m not going to bother telling you about them, because this is going to be different for everyone, on every different site. Your mileage may vary. I will say this:

  • This is a good time to stop and do things right. If you see Divi components and designs that are broken because someone messed with controls until it looked right, consider if there’s a simpler, more forward-thinking way to get the same result with less tinkering. For example if someone is using negative margins to get things to align, consider whether a grid or flex positioning on the same items would do the same thing.
  • Prefer fixing by subtraction. When you see things break, your mind might immediately consider what CSS rule you can shim in to fix it. Go look at your custom CSS, and the settings on the broken component and its containers that might have caused the problem in the first place. Often you’re going to find that a shim you needed on the old version just isn’t necessary, and removing it might solve your problem.