There's no direct path from Craft 3 to Craft 5 — and Craft was still the easy part.
This year I moved a Craft 3 site that had been running for years to Craft 5. It's a private portal where a company shares large media files with its clients: about 40,000 entries, 86,000 assets on Amazon S3, a handful of plugins and a custom one that builds zip downloads. The site had been through several agencies, and earlier attempts to upgrade it had stopped halfway.
The Craft migrations did their job. Almost everything that broke was around Craft: S3, file paths, permissions, licences and DNS. Here's what happened.
Check what the site runs on the server
The first plan was to move to managed Craft hosting as part of the upgrade. That didn't work out: the site runs ffmpeg on the server to process media, and the host didn't support it. We stayed on a plain VPS with a fresh setup.
Before you choose hosting, write down every program the site runs on the server: ffmpeg, ImageMagick, Ghostscript, wkhtmltopdf.
Two steps, three branches
You can't jump from Craft 3 straight to 5. You have to go through Craft 4. So the project got three branches — craft-3, craft-4 and craft-5 — each with its own code, composer.lock and project config.
The database migration ran locally in DDEV:
- Import the production backup on the Craft 3 branch and run
craft up. - Switch to the Craft 4 branch, run
composer installandcraft up. - Do the same on the Craft 5 branch.
- Export the database and import it on the new server.
The Craft 3 project ran on PHP 7.4 and Craft 5 needs 8.2 or newer, so DDEV's PHP version changed between steps. The database version stayed the same. The new server never ran anything but Craft 5: it spent its first weeks as staging, reachable by IP, and on launch day it simply became production.
Do a test run on real data
A month before launch we did the whole move on a fresh production backup and checked the result: entry, asset and user counts before and after, and whether the newest production entry made it across. Everything that surprised us went into a step-by-step list.
On launch day we just followed that list. It took about an hour from the backup to a checked new server.
What broke
An S3 policy only Craft 5 noticed
On Craft 5, every upload failed with Unable to check if <file> exists.
The bucket policy had a Deny s3:ListBucket rule for everyone, meant to stop the public from listing files. It also blocked the site's own IAM user. Without that permission, S3 answers a check for a missing file with 403 instead of 404.
Craft 3 (Flysystem v1) quietly read that 403 as "the file doesn't exist". Craft 5 (Flysystem v3) throws an error. Same bucket, same policy — it just never mattered before.
The fix was one condition on the Deny rule that makes an exception for the site's IAM user (ArnNotEquals on aws:PrincipalArn). The public still can't list the bucket. The test run caught this. Without it, uploads would have broken on launch day.
Missing UIDs: don't make up new ones
Craft 5's content migration stopped on 49 field layout tabs and elements that had no UID. Craft 5 stores content as JSON, with those UIDs as the keys, so it needs them.
The usual quick fix is a script that generates random UIDs. Here that would have gone badly, and nobody would have noticed at first: the Craft 5 project config already had its own UIDs for those elements. With random ones, the content would point at nothing. No error — it would just be gone from the control panel and the site.
So we looked up each missing UID in the Craft 5 project config and committed them to the Craft 4 branch. A normal craft up on Craft 4 then wrote the right UIDs before the Craft 5 migration ran. Over 154,000 content values moved, none lost. (A different UID problem, duplicates, came up in my Craft 4 to 5 upgrade.)
Small renames that break quietly
-
ENVIRONMENTis nowCRAFT_ENVIRONMENT. Craft 3-era.envfiles use the old name. Craft 4 and 5 don't see it and assume production — locally that made project config read-only, with no explanation. - Super Table fields are now queries. A template that read
asset.technicalSpecs.resolutionnow needsasset.technicalSpecs.one().resolution. Search your templates for every Super Table and Matrix field used like a single object.
Files written where they can't be
The new server deploys in releases: every deploy replaces the project folder, and PHP can't write to it. That's how three old problems showed up:
- the zip plugin wrote to a relative path that ended up inside
web/— moved to Craft's temp folder; - generated media previews were saved under the project root — moved to
storage/, which is shared between releases; - a filesystem in project config had absolute paths from the old server — replaced with
@webrootand@web.
A nice bonus: those previews had never actually been saved on the old server, so pages got faster after the upgrade.
After one deploy, every control panel page returned a 500. Craft rewrites the project config YAML files, and they belonged to the deploy user, not the PHP user. Putting both users in one group and letting that group write to the folder (with the setgid bit) fixed it. Check this before you run craft up on launch day.
A licence banner that came with the real domain
On staging, a trial plugin showed a small "trial" notice. As soon as the site ran on its real domain, Craft saw it as production and put a red "Purchase required" banner across the control panel. The plugin turned out to be unused, so we removed it before the DNS switch.
Test the control panel on the real hostname before launch — the /etc/hosts trick below does exactly that.
Update Craft 5 once more before launch
Our test run was on Craft 5.9, and by launch day that version had known security issues. So we updated to the latest 5.x and ran composer audit before going live, not after.
An upgrade is also a good moment to delete things. We removed a public phpinfo() file, an IIS web.config on an nginx server, a forgotten folder in the web root, and Redactor, replaced by CKEditor.
Switching DNS you don't control
The domain's DNS was managed by someone else, and every change was an email. Here's how we kept the switch calm:
- Copy the TLS certificate from the old server ahead of time, so HTTPS works the moment DNS changes. Set up automatic renewal on the new server afterwards.
- Test the real domain before DNS changes. Add
<new IP> <domain>to/etc/hostson your own machine and open the site in a private window. You see the real hostname, certificate and URLs. - Freeze only the control panel. Only staff add content; clients just view and download. So the public site stayed up on the old server until DNS moved, and visitors had no downtime.
- Keep a way back: a DDEV snapshot, a backup of the new server's staging database, and the old server running for a week or two.
A checklist for your Craft 3 → 5 upgrade
- Go through Craft 4, one branch per version, and migrate locally.
- Write down the programs the site runs on the server before you choose hosting.
- Do a test run on a fresh production backup and write down every step.
- Check counts and the newest entry after every run.
- Fill missing UIDs from your project config, never with random values.
- Review S3 bucket policies, file paths and folder permissions.
- Test the control panel on the real domain through
/etc/hosts. - Update to the latest Craft 5 and run
composer auditbefore launch.
Quick answers
Can I upgrade from Craft 3 straight to Craft 5?
No. You have to go through Craft 4 first. Run each version's migrations in order, ideally locally on a copy of the production database.
Why do uploads fail with "Unable to check if file exists" after upgrading to Craft 5?
Often it's the S3 bucket policy. If the site's own user isn't allowed to list the bucket, S3 answers 403 instead of 404 for a missing file. Craft 3 ignored that; Craft 5 doesn't. Make sure the policy doesn't deny s3:ListBucket to the site's IAM user.
How do I fix "Field layout element is missing its UUID"?
Add the missing UIDs on Craft 4, before the Craft 5 migration runs. If you already have a Craft 5 project config, take the UIDs from there instead of generating random ones — otherwise content can quietly disappear.
Originally published on b10k.nl. I'm Bohdan, a freelance Craft CMS developer in the Netherlands. Planning the next step? Here's how I help with the move to Craft 6.
