Strapi Cloud Migration: Lessons Learned Migrating v4 to v5

When you look at the official documentation, the migration steps from Strapi v4 to v5 feel straightforward:

“Make a backup, run the script and simply deploy.” And technically, that’s true...

But in practice, moving a live project on Strapi Cloud involves a lot of little decisions, edge cases, and “gotchas” that the docs can’t possibly cover in detail.

At NOTUM Technologies , we’ve guided several projects through this upgrade, and here are the key lessons we learned along the way.

1. Backups Are More Than a Checkbox

Creating a backup is obvious, but two details really matter:

• Always download a local copy. If something goes wrong mid-migration on Strapi Cloud, having a local .sql dump lets you restore quickly and gives you peace of mind.
• Tag it in Git before migration. We commit the last v4 state (for example, v4-backup) so we always know exactly where to roll back if needed. It’s a small thing, but when you’re under pressure, it makes a big difference.

2. The Migration Script Does Its Job, But Review Carefully

The official upgrade script is a great starting point, but it takes a cautious approach:

• Lifecycles are commented out. Some will still work as-is; others need changes. Treat this as a reminder to review and test each hook individually, rather than blindly restoring everything.
• TODO markers are your friends. The script flags potential issues. We learned not to ignore them - each TODO represents a spot that could cause unexpected behaviour later.

3. API Changes Are Where Most Work Happens

The biggest shift between v4 and v5 is in the API responses:

• id → documentId. A small change in name, but one that breaks assumptions across frontends and external systems.
• No more .data and .attributes. Consumers need to be updated to access fields directly.

If you need time to refactor, Strapi provides compatibility options:

• REST: set header Strapi-Response-Format: v4
• GraphQL: enable v4CompatibilityMode: true in config/plugins.js

These flags buy you breathing room, but we recommend planning the full refactor sooner rather than later.

4. Test in a Staging Environment First

Running the migration locally is important, but we discovered some issues only surfaced in a hosted environment. Our approach:

• Spin up a Heroku instance, import the v4 database dump, and run the migrated project there.
• Test user flows, roles, and permissions in a safe sandbox before touching production.

This step saved us from surprises that never appeared on local.

5. Deployment Errors Aren’t Always Errors

One unexpected challenge: sometimes Strapi Cloud marks a deployment as failed because the health check times out, even though the app is actually running fine.

Our process:

• Always check the Strapi Admin URL directly.
• If the app is live, retry the deployment using Trigger deployment - it passed on the second attempt.

This simple check helped avoid unnecessary panic and rollbacks.

6. Migration Is Also a Code Audit

The upgrade script gets you across the line, but the real value of the migration is in the review process:

• Do your lifecycle hooks still make sense?
• Are you consuming APIs in a way that aligns with v5’s cleaner responses?
• Can you simplify or modernise parts of your codebase during the transition?

Migration is a great opportunity to clean house, not just to “make it work again.”

Final Thoughts

Strapi v5 brings important improvements, but migration isn’t just about running a script; it’s about planning, testing, and taking the opportunity to improve your codebase.

The official documentation gives you a solid foundation. The lessons above are what we learned in the real world: back up smartly, review lifecycles, handle API changes carefully, and always test in a staging environment.

With the right preparation, moving to v5 is not only manageable but also a chance to strengthen your project for the future.

Do you have a question about the v4 to v5 migration? Drop it in the comments.

Big thanks to Gábor Filip Ónodi-Pető for writing this article 🙌