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.