Why and when a v4 project needs to move
Strapi v4 reached end of life on April 30, 2026. Its final release, 4.26.2 of June 9, 2026, will receive no further updates. A v4 project that stays where it is will not get patched when a vulnerability is found in Strapi itself, and the risk grows as the Node.js runtime, database drivers and npm dependencies around it move on. The first decision is therefore not whether v5 is better, but how long the team can run an unsupported CMS that holds content and APIs for live products.
Most teams move for one of four reasons. A security review may have flagged the v4 version, the admin panel, or outdated dependencies. The Node.js version or database server the team plans to run may fall outside what Strapi 5 supports, which requires PostgreSQL 14 or later, MySQL 8.0 or later, MariaDB 10.3 or later or SQLite 3, and only Active or Maintenance LTS Node.js versions. A needed plugin may exist only for v5. A planned front-end rewrite may make it cheaper to change the API contract at the same time. Confirm which of these applies before you set a date.
Plan the work by counting what will change. List every installed plugin, every custom controller, service and lifecycle hook, every integration that calls the REST or GraphQL API, and every front end that reads responses. Teams usually compare their own capacity with a partner's by these counts, because plugin compatibility, custom code and integrations drive most of the effort. Ask for this inventory in writing before you agree on scope or timing.
The migration changes the API contract as well as the code. Strapi 5 replaces the Entity Service API with the Document Service API and changes the API response format. A header, Strapi-Response-Format: v4, is available for backward compatibility during migration, but it is a bridge, not a permanent setting. Every consumer of your API, including mobile apps and third-party systems, must be tested against the new format before cutover, and the team should decide whether that testing is done in-house or by a partner.
What the migration includes
A v4 to v5 move is a set of linked work packages, each with its own checks. The cards below cover the work we would scope in writing before a migration starts.
Inventory of the v4 project
We catalog content types, custom controllers, services, lifecycle hooks, plugins, custom admin panel code and environment config. This inventory sets the scope, reveals which code depends on v4 behavior, and shows which items need a decision before any upgrade work begins.
Upgrade tool and codemod runs
We run the Strapi upgrade tool and its codemods against a copy of the project, then review every automated change in version control. Codemods cover only part of the work, so each change is checked against the project's own code before it is accepted.
Manual fixes for breaking changes
Breaking changes listed in Strapi's migration docs are fixed by hand where codemods do not reach. Each fix is traced to a specific file and reviewed, so the team can see which project code changed because of a documented breaking change and which changed for other reasons.
Document Service API migration
Strapi 5 replaces the Entity Service API with the Document Service API. We move each Entity Service call in custom controllers, services and hooks, and we confirm the behavior of drafts, publishing and locales against the old version, since these are where silent differences tend to appear.
Plugin updates or replacements
Each installed plugin is checked for a Strapi 5 compatible release. Where none exists, we decide with you whether to replace it, rebuild the feature inside a custom plugin, or drop it. Each choice is recorded with its owner and its effect on the content model.
Front-end consumer adjustments
Front ends must handle the Strapi 5 response format. During transition, the Strapi-Response-Format: v4 header can keep existing consumers working. We map every consumer, mark which ones move to the new format now, and set a removal point for the header.
Data migration script rehearsal
Strapi 5 runs data migration scripts on first start. We rehearse them on a restored copy of the production database, time the run, record each row count before and after, and log any record that fails to convert so it can be fixed before cutover.
Rollback documentation and testing
Strapi's docs say to back up the database first because downgrading is not supported. The rollback therefore relies on a verified database backup and a restore path. We document it and test restoring it on a staging copy before cutover is approved.
Migration report and regression tests
The migration report records every change, decision and open item. The regression test set covers public API responses, roles and permissions, and admin workflows. Together they show whether the upgraded project behaves as the v4 project did, with differences recorded and approved.
Cutover runbook
The cutover runbook lists the steps, owners, checks and go or no-go criteria for the production switch, including the backup point, the start of the Strapi 5 data migration and the rollback trigger. The runbook is rehearsed on staging before the production window is set.
What drives effort and duration
This table lists the factors that most change how much work a Strapi v4 to v5 migration takes, why each one matters and how to keep it under control.
| Driver | Why it matters | How to reduce it |
|---|---|---|
| Custom controllers, services and lifecycle hooks | Code that calls the v4 Entity Service or relies on v4 hook behavior needs manual rewrites against the Document Service API, and the codemods do not cover all of it. | Inventory every custom controller, service and lifecycle hook before estimating, and remove dead code or move logic into thin, well-tested services first. |
| Number and depth of plugins | Each plugin must have a Strapi 5 compatible release, and plugins with deep integration into content or admin code can block the upgrade until they are updated or replaced. | List every installed plugin with its v5 compatibility status, drop unused plugins, and decide early which custom plugins need rewriting. |
| Volume and shape of content | Large collections, deep component or dynamic zone nesting and many draft and published pairs increase data migration run time and the number of records to verify. | Count entries per content type, note nested components and relations, and run the data migration against a recent production copy to measure real run time. |
| Media files and upload configuration | Uploaded files, image format variants and custom upload providers add storage to back up and paths to verify after the move. | Confirm where media is stored, check that the upload provider works with Strapi 5, and sample-test file URLs in the staging environment. |
| Front ends and external consumers on the v4 response format | Strapi 5 changes the API response format, so every front end, mobile app and integration that parses v4 responses must be tested or adapted. | List each consumer, decide whether to use the Strapi-Response-Format: v4 header during transition, and test each consumer against staging responses. |
| Database engine and version | Strapi 5 supports PostgreSQL 14 or later, MySQL 8.0 or later, MariaDB 10.3 or later and SQLite 3. Older engine versions or unsupported engines require upgrade or migration work before Strapi 5 can run. | Confirm the engine and exact version in each environment against the Strapi installation requirements, and plan any database upgrade as a separate, tested step. |
| NoSQL or other unsupported data stores | Strapi 5 does not support MongoDB or other NoSQL databases. Moving to a supported relational engine is a separate project that adds schema design, data conversion and testing. | Identify any NoSQL store early, scope its conversion separately, and confirm the target relational engine before the migration plan is approved. |
| Number of environments to migrate and test | Each environment (development, staging, production and any preview or regional copies) needs its own data migration run, configuration check and regression test. | Use one repeatable migration script and runbook across all environments, and reduce the number of long-lived environments where possible. |
| Compliance evidence requirements | Assessors may ask for pre-migration backups, change records, test results, access reviews and proof of a working rollback, which adds documentation work to each stage. | Agree the evidence list with your compliance lead and auditor before work starts, and record test and rollback results as the migration runs. |
Migration phases and outputs
The sequence moves a Strapi v4 project to Strapi 5 in stages, and each stage closes with a written output that the next stage depends on.
Inventory dependencies, plugins and custom code
The team lists every Strapi plugin, npm dependency, custom controller, service, lifecycle hook and admin extension, then maps which front ends and integrations call the API. The output is a dependency and plugin list, a custom code map and a consumer list, reviewed by the client's engineering lead before any work starts.
Set up the target environment
The team builds a staging environment that uses a Node.js version on Strapi's supported Active or Maintenance LTS list and a database version the Strapi 5 installation requirements support. The output is a documented environment record, with versions confirmed against the current Strapi installation docs at the time of build.
Rehearse the upgrade on a production data copy
The team restores a recent copy of production data into the staging environment and runs the Strapi upgrade tool and codemods against a version-controlled branch. The output is a rehearsal log listing every codemod change, every failed step and the remaining errors that need manual work.
Remediate code and plugins by hand
Engineers rewrite code the codemods could not handle, including Entity Service calls that move to the Document Service API, and replace or update plugins that lack Strar 5 support. The output is a branch where the test suite passes and the dependency list shows a Strapi 5 compatible version for every plugin, with any unresolved plugin flagged to the client.
Adapt the front ends and run contract tests
The team updates each consumer for the v5 response format or uses the Strapi-Response-Format: v4 header during transition, then runs contract tests against every endpoint listed in the consumer map. The output is a passing contract test report per consumer and a list of any endpoints still returning v4 shapes.
Rehearse the full data migration and rollback
The team runs the data migration scripts against a fresh production copy several times, timing each run, then performs a rollback drill that restores the pre-migration database backup and brings the v4 application back online. The output is a timed run record and a verified rollback runbook that the client has signed off on.
Cut over with a backup taken first
On the agreed cutover window, the team takes a fresh database backup before any change, puts the v4 instance in read-only or maintenance mode, runs the migration and switches traffic to Strapi 5. The output is a cutover record with the backup location and checksum, because Strapi's docs say downgrading is not supported, so restoring that backup is the only rollback path.
Review the system after cutover
After traffic has run on Strapi 5 for a period agreed with the client, the team reviews error logs, API response checks, plugin behavior and backup jobs, then hands over the runbooks. The output is a post-cutover review report with open issues, owners and the ongoing support scope.
What teams keep in-house and what they outsource
This table shows which migration work usually stays with the client team, which is shared, and which is commonly outsourced, along with the skills each part needs so you can match work to people before scoping.
| Work part | Usual owner | Skills required |
|---|---|---|
| Content model change decisions | In-house product owner | Content modeling, knowledge of editorial workflows, and sign-off authority over field and relation changes |
| Validation of migrated entries | In-house content editors | Domain knowledge of published content, draft and publish states, and media references |
| Production database and backups | In-house platform or DBA team | Database administration for PostgreSQL, MySQL, MariaDB or SQLite, backup and restore, and point-in-time recovery |
| Inventory and dependency analysis | Shared, often led by a partner | Node.js and TypeScript, reading the Strapi v4 codebase, and mapping plugins and custom code |
| Codemod runs and custom code refactoring | Outsourced or shared with in-house developers | Node.js and TypeScript, the Strapi upgrade tool and codemods, and code review of automated changes |
| Document Service API rewrites | Outsourced or shared with in-house developers | Strapi 5 Document Service API, the former Entity Service API, and query and lifecycle hook behavior |
| Plugin compatibility decisions | Shared between product owner and developers | Plugin maintainer status review, version matching to Strapi 5, and replacement or removal trade-offs |
| Front-end contract testing | In-house front-end team with partner support | Front-end development, API response format knowledge, and the Strapi-Response-Format v4 header during transition |
| Rehearsal, rollback and cutover support | Outsourced planning, in-house sign-off | Staging environment operations, backup restore testing, and cutover runbooks, since downgrading is not supported |
What usually goes wrong
Most failed Strapi v4 to v5 migrations break in a small number of predictable places. Each risk below names the prevention step to put in the plan before the first start of Strapi 5.
Starting Strapi 5 without a backup
Strapi 5 runs data migration scripts on its first start, and the docs state that downgrading is not supported. Take a full database backup and confirm it restores before that first start. Without it, returning to v4 means rebuilding data by hand.
Plugins discovered without v5 releases
A plugin with no Strapi 5 release can stop the upgrade late, after estimates are agreed. Build a full inventory of plugins and custom packages during scoping, check each one against its v5 release status, and decide replace, fork or remove before the build starts.
Custom code relying on Entity Service shapes
Code written against the Entity Service API can keep running while returning data in a different shape under the Document Service API. These changes are silent, so type errors and failed requests may never appear. Find every call site in the inventory and cover each with tests that assert the returned shape.
Front ends broken by the response format
Strapi 5 changes the API response format, and the Strapi-Response-Format: v4 header exists for backward compatibility during migration. A front end that was never tested against the new format can break after cutover. Write a contract test for each consumer, including web, mobile and preview clients, and run it against both formats.
Unsupported Node.js or database versions
Strapi 5 runs only on Active or Maintenance LTS Node.js versions and supports PostgreSQL 14 or later, MySQL 8.0 or later, MariaDB 10.3 or later and SQLite 3. Pin the exact Node.js and database versions in the build and in the staging environment, and confirm both against the current installation requirements before testing.
Data migration tested only on a sample
A migration script that ran once on a small sample can fail on production content with unusual fields, long text, relations or media records. Run the scripts on a full copy of production as many times as needed, compare record counts and sampled content, and record the timing so the cutover window is based on real data.
Rollback documented but never restored
A rollback plan that exists only on paper usually fails when it is needed. Run a restore drill on a copy of production that covers the database, uploads and configuration, then time it and log each step. Repeat the drill after any change to the migration plan.
How the work differs by starting point
A v4 project with few plugins and a standard database is closest to the path Strapi documents for v4 to v5. The work centers on running the upgrade tool and codemods, reviewing the breaking changes list, and testing the API responses your front end depends on.
- Database: confirm the engine and version are on the Strapi 5 support list, such as PostgreSQL 14 or later or MySQL 8.0 or later.
- Plugins: check each installed plugin for a Strapi 5 release before starting, since plugin compatibility often sets the order of work.
- Front end: decide whether consumers move to the v5 response format now or use the Strapi-Response-Format: v4 header during transition.
- Node.js: move to an Active or Maintenance LTS version, which Strapi 5 requires.
- Rollback: take and test a database backup first, because the docs say downgrading is not supported.
A v4 project with custom admin panel code and many lifecycle hooks has most of its effort in application code, not in the upgrade tool. Custom services and hooks written against the Entity Service API must be reworked for the Document Service API, and each change needs tests that prove the behavior held.
- Code inventory: list every lifecycle hook, custom controller and service, and admin panel extension before estimating the work.
- Document Service API: plan the rewrite of calls that depend on the old Entity Service behavior and response shape.
- Admin panel: review each customization against the v5 admin panel changes and rebuild those that no longer load.
- Admin SSO and Enterprise features: if you use admin SSO (Growth add-on) or audit logs and review workflows (Enterprise), confirm current plan terms, since these are listed on Strapi's pricing page and may change.
- Regression tests: cover hook side effects, such as derived fields and notifications, before the cutover.
Strapi 5 does not support MongoDB or other NoSQL databases, so a v4 project on one of these stores must move to a supported relational database before or during the upgrade. This is a data project as much as an upgrade project, and it should be scoped separately.
- Target database: choose PostgreSQL, MySQL, MariaDB or SQLite and confirm the version meets the Strapi 5 installation requirements.
- Schema mapping: map v4 content types, components, dynamic zones and relations to the relational structure, and document each decision.
- Sequence: decide whether the database move happens on v4 first or alongside the upgrade, and confirm with Strapi's migration docs that the chosen order is supported.
- Media and references: verify that upload records, relation IDs and localized entries survive the move.
- Reconciliation: compare record counts and sample content between source and target before any cutover.
A v4 project self-hosted on Kubernetes or VMs with several instances behind a load balancer needs a deployment plan, not only a code plan. Strapi's data migration scripts run on the first start of Strapi 5, so the fleet must not serve traffic on mixed versions against one database during the change.
- Migration run: confirm with Strapi's docs how the data migration behaves when several instances start, and designate one controlled start for it.
- Traffic: plan a maintenance window that drains or stops v4 instances before v5 starts, because a rolling update can mix versions.
- Shared resources: confirm that the external database and upload provider are reachable from v5 instances and that media paths are unchanged.
- Caching and sessions: review any cache layer or session state that stores v4 response formats.
- Rollback: keep the pre-upgrade database backup and the v4 image or artifact ready, since downgrading is not supported.
An air-gapped v4 project depends on everything being staged in advance. The upgrade tool, codemods, npm packages, Node.js runtime, database drivers and plugin releases must be available inside the network before the change window opens.
- Artifact mirror: stage the upgrade tool, codemods, dependencies and Node.js runtime in an internal registry or artifact store.
- Version pinning: choose one Strapi 5 release to stage, since minor releases ship about weekly and the target must be fixed in advance.
- Plugin releases: download and test each Strapi 5 plugin release, then confirm its own dependencies can be mirrored.
- Documentation: keep offline copies of the migration docs and breaking changes list that match the staged version.
- Dry run: rehearse the full upgrade in an isolated copy of the environment, including the database backup and restore.
What you need to provide
Most of the migration delay we would expect comes from inputs that are missing on day one, so the first job is to collect them in writing. The source repository must contain the v4 code and its lockfile, so the upgrade tool and codemods run against exactly what is in production. You also need read access to the production database schema and a recent copy of the database for rehearsal. Without a recent copy, the data migration scripts that run on first start of Strapi 5 cannot be tested against your real content.
Provide a list of every installed plugin with its version, and a list of every front end, mobile app and integration that calls the API. Plugin compatibility and front-end response format changes are the two areas where a v4 to v5 move most often breaks something that was not on anyone's list. Each consumer should have a named owner who can confirm which response format it expects and whether it can be tested against a staging instance. Staging environments should match production in database engine, Node.js version, media storage and environment configuration.
Name owners for content model decisions and for content validation. The content model owner settles questions such as field changes that the migration exposes, and the content validation owner checks migrated entries against the source. Agree a change window and freeze rules with the business, including who can approve an exception. Confirm access to your backup and restore tooling and make sure someone can run a restore in a rehearsal, because Strapi's documentation says to back up the database first and that downgrading is not supported.
Decide the target Node.js and database versions from the lists in Strapi's installation requirements before the rehearsal starts. Strapi 5 runs only on Active or Maintenance LTS Node.js versions and supports PostgreSQL 14 or later, MySQL 8.0 or later, MariaDB 10.3 or later and SQLite 3, but not MongoDB. Finally, name who signs off the regression results and who makes the go or no-go call at cutover. These should be different people from the team running the migration, so that the decision is not made by the people who have the most reason to proceed.
Frequently asked questions
How much does a Strapi v4 to v5 migration cost and how long does it take?
The price and duration are both set by a written scope built from an inventory of your project. The main cost drivers are custom code, the number of plugins and how many need changes, the consumers that call your API (front ends, mobile apps and integrations), data volume, and how many environments must be migrated and tested. There is no fixed duration, so ask for a timeline in the same document as the price. The migration itself is one-time work. Ongoing minor releases and support are a separate, recurring cost. Any quote should list each driver, the rehearsal runs planned and what you provide, such as access, test data and decision makers.
Can our own team migrate Strapi v4 to v5 without a partner?
Yes, if your team has Node.js and database skills and time to rehearse. Strapi publishes an upgrade tool with codemods, a breaking changes list and data migration scripts that run on the first start of Strapi 5, so the path is documented. The hard part is rehearsal. You need a copy of production data, a full upgrade run on that copy, and a review of every custom controller, service, lifecycle hook and plugin against the Document Service API changes. Check whether your team can run those rehearsals while keeping the live system stable.
Can we roll back a Strapi 5 migration after go-live?
Only by restoring a verified database backup. Strapi's documentation says to back up the database first because downgrading from Strapi 5 to v4 is not supported. Treat that backup as your rollback plan. Take it immediately before cutover, confirm you can restore it into a clean environment, and time the restore on a rehearsal copy. Content written in Strapi 5 after cutover would be lost on a restore to the pre-migration backup, so agree in advance how edits made during the cutover window are handled and who makes the call to roll back.
Does our front end have to change when we move to Strapi 5?
It may. Strapi 5 changes the API response format and replaces the Entity Service API with the Document Service API, so any front end that parses responses needs review. Strapi provides a Strapi-Response-Format: v4 header for backward compatibility during migration. Teams can use it to keep existing front ends working while client code is updated in stages, then remove the header once every consumer reads the new format. Inventory every consumer, including mobile apps and third-party integrations you do not control, and confirm the header behavior in the current Strapi docs before you rely on it.
Does Strapi 5 run on the database we already use?
Only if the database is a supported engine. Strapi 5 supports PostgreSQL 14 or later, MySQL 8.0 or later, MariaDB 10.3 or later and SQLite 3. It does not support MongoDB or other NoSQL databases, so a NoSQL-backed Strapi project needs a different data path before it can move. Check your engine and version against these requirements early, since a database upgrade may be needed first. Also confirm that the Node.js version you plan to run is an Active or Maintenance LTS release, because Strapi 5 runs only on those versions.
What support does a Strapi 5 project need after the migration goes live?
Plan for ongoing minor releases. Strapi 5 minor releases have shipped roughly weekly, for example v5.56.0 on September 30 and v5.57.0 on October 7, 2026, so a live project falls behind quickly. Keeping current covers upgrades, Node.js LTS changes, plugin updates and dependency security fixes. This work recurs and is available from DeployOpen as an upgrade and support retainer. Ask who applies each update, how updates are tested before production, and what release cadence will be followed. Strapi v4 reached end of life on April 30, 2026, so the migration itself should not be delayed.
How DeployOpen runs this migration
DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside your own infrastructure, and a Strapi v4 to v5 migration follows the same written-scope approach. The work moves an end-of-life v4 project onto Strapi 5 with the upgrade tool, codemods, data migration and a tested rollback path.
How we scope
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- The written scope lists every content type, custom controller, service and plugin that must move to the Document Service API.
- We inventory third-party plugins and check each one for Strapi 5 compatibility before estimating the build.
- The scope names which front ends consume v4 response formats and whether the Strapi-Response-Format: v4 header is needed during cutover.
- It confirms your database engine against Strapi 5 support, including PostgreSQL 14 or later and MySQL 8.0 or later.
How we build
- We run the upgrade tool and codemods on a copy of the project, then review each change the codemods make.
- Custom code that calls the Entity Service API is rewritten against the Document Service API and tested function by function.
- Data migration scripts are rehearsed on a restored copy of the production database before any cutover date is set.
- Every migration step is paired with a tested rollback, since the Strapi documentation states that downgrading is not supported.
- Node.js is aligned to an Active or Maintenance LTS version that Strapi 5 supports before the first test run.
How we hand over
- You receive the migrated code, configuration and an updated runbook describing the cutover and rollback steps.
- The handover documents every breaking change that affected your project and how each one was resolved.
- Test results cover content read and write paths, role permissions, plugin behavior and front-end responses.
- Database backup and restore procedures are written down and demonstrated before go-live.
- Your team receives a list of open items, such as plugins still pending upstream updates, with owners named.
How we support
- Ongoing support is available as a retainer for patching Strapi 5 minor releases, which ship roughly weekly, and plugin updates.
- Retainers can cover Node.js LTS changes and dependency security fixes after the cutover is complete.
- Post-migration monitoring checks API response formats and error rates for an agreed period set in the written scope.
- Support requests are handled against the terms in the retainer agreement, which you review before signing.
- Confirm with DeployOpen during scoping which support hours, response targets and escalation paths the retainer includes.
