Strapi v4 to Strapi 5 breaking changes

The present page lists all the breaking changes introduced in Strapi 5. Breaking changes are grouped into topic-related categories, and for each line in the following tables line you will find:

• a short description of the breaking change,
• and 2 other columns, "Affects plugins" and "Handled by codemods", that sum up whether the breaking change also affects plugins and whether the breaking change is automatically handled by a codemod from the upgrade CLI tool.

You can click on the description of any breaking change in the following tables to jump to the corresponding page with more details.

💡 Tips

• To view a full list of available codemods, run the npx @strapi/upgrade codemods ls command in your terminal.
• To have a deeper look at the code executed by the codemods, head over to the list of codemods in the GitHub repository.

❗️ Warning: Strapi 5 is not stable yet

It is strongly advised not to upgrade a critical or production-ready project from Strapi v4 to Strapi 5.

The content of migration resources might not be final yet. Migration resources are currently only provided to prepare you for the upgrade to Strapi 5 when it is released as a stable version.

Strapi 5 is currently only provided as a Release Candidate (RC) version and is not meant to be used in production yet.

Database

Description	Affects plugins	Handled by codemods
MySQL v5 is not supported anymore	No	No
Database identifiers longer than 55 characters will be automatically shortened	Yes	✅ Yes
Only the better-sqlite3 package is supported for the SQLite client	No	✅ Yes
Only the mysql2 package is supported for the MySQL client	No	✅ Yes

Dependencies

Description	Affects plugins	Handled by codemods
The CLI default package manager is not yarn anymore	No	No
Vite is the default bundler in Strapi 5	Yes	No
Strapi 5 uses react-router-dom v6	Yes	✅ Yes
Strapi 5 uses koa-body v6	Yes	No
Webpack aliases are removed in Strapi 5	Yes	No
Apollo Server v3 upgraded to Apollo Server v4	Yes	No

Configuration

Description	Affects plugins	Handled by codemods
Some env-only configuration options are handled by the server configuration	No	No
Configuration filenames should meet strict requirements	No	No
Server log level is http	No	No
Model config path uses uid instead of dot notation	Yes	👷 Partly
The webhooks.populateRelations server configuration is removed	Yes	No
The defaultIndex option is removed from the public middleware	No	No
Server proxy configuration options are grouped under the server.proxy object	No	No

Strapi objects, methods, packages, and back-end customization

Description	Affects plugins	Handled by codemods
strapi.fetch uses the native fetch() API	Yes	No
strapi factories import have changed	Yes	👷 Partly
The isSupportedImage method is removed in Strapi 5	Yes	No
strapi-utils has been refactored	Yes	✅ Yes
Core service methods use the Document Service API	Yes	No
i18n is now part of the strapi core	Yes	✅ Yes

Plugins, providers, and admin panel customization

Description	Affects plugins	Handled by codemods
Users & Permissions register.allowedFields defaults to []	No	✅ Yes
The helper-plugin is deprecated	Yes	No
injectContentManagerComponent() is removed in favor of getPlugin('content-manager').injectComponent()	Yes	No
Some Mailgun provider legacy variables are not supported	Yes	No
The lockIcon property has been replaced by licenseOnly	Yes	No
The ContentManagerAppState redux is modified	Yes	No
The EditViewLayout and ListViewLayout have been refactored	Yes	No
The Admin Panel RBAC redux store has been updated	Yes	No
The getWhere method for permission provider instances has been removed	Yes	No

Content API

Description	Affects plugins	Handled by codemods
Strapi 5 has a new, flattened response format for API calls	Yes	No
REST API input is validated by default in controllers	Yes	No
The GraphQL API has been updated	Yes	No
The Entity Service API is deprecated and replaced by the Document Service API	Yes	👷 Partly
documentId should be used instead of id in API calls	Yes	👷 Partly
Database lifecycle hooks are triggered differently based on Document Service API methods	Yes	No
The publicationState parameter is not supported and replaced by status	Yes	✅ Yes
Sorting by id is no longer possible to sort by chronological order	Yes	✅ Yes
There is no findPage() method with the Document Service API	Yes	No
The localizations field does not exist anymore	Yes	No
Some attributes and content-types names are reserved by Strapi	Yes	No
Upload a file at entry creation is no longer possible	Yes	No