Empty morphMany relations return [] instead of null when populated

Page summary:

In Strapi 5, populating an empty morphMany relation -- including type: 'media', multiple: true fields such as a gallery -- returns [] instead of null. Update client code that checks field === null to treat [] as the empty state.

In Strapi 5, empty morphMany relations and type: 'media', multiple: true fields (such as a gallery) now serialize as an empty array when populated, consistent with oneToMany and manyToMany relations. Previously, these fields returned null when no related entries existed.

This page is part of the breaking changes database and provides information about the breaking change and additional instructions to migrate from Strapi v4 to Strapi 5.

 Is this breaking change affecting plugins?Yes

 Is this breaking change automatically handled by a codemod?No

Breaking change description

In Strapi v4

Populating an empty morphMany relation or a multiple media field returned null:

{
  "gallery": null
}

In Strapi 5

Populating an empty morphMany relation or a multiple media field returns an empty array:

{
  "gallery": []
}

Migration

This section regroups useful notes and procedures about the introduced breaking change.

Notes

• This change applies to all morphMany relation types, including type: 'media', multiple: true fields (for example, gallery fields).
• The change is unconditional and is not controlled by the api.documents.strictRelations setting.
• See Document Service API: Populating fields and REST API: Population & Field Selection for related information on populating relations.

Manual procedure

Check client code, webhooks, and integrations that consume populated morphMany or multiple media fields.

1. Search your codebase for code that branches on field === null or treats null as "no value" for populated morphMany or multiple media fields.
2. Replace null checks with array checks, for example using !field?.length.

Before

if (entry.gallery === null) {
  // handle empty gallery
}

After

if (!entry.gallery?.length) {
  // handle empty gallery
}