Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages

Help for owners

I upgraded Strapi and my website stopped working

Short answer

Strapi 5 changes the response format and IDs that front ends depend on. Strapi documents a compatibility header and setting to keep the old format during a refactor, says always back up the database, and says there is no automated downgrade: to go back, restore the backup and the matching code.

  • Written for business owners
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Does this sound like your situation?

  • The website shows empty pages or errors after the Strapi upgrade.
  • Fields that used to be inside attributes are now missing or in a different place.
  • Links and lookups by number no longer find the content.
  • My developer says it cannot go back.
  • I did not take a backup before the upgrade.

Why does this happen?

  1. The response format changed

    Strapi says responses no longer use the v4 attributes wrapper. A front end written for the old shape reads nothing from the new one. Strapi documents a Strapi-Response-Format: v4 header for REST, and a v4CompatibilityMode setting for GraphQL, to keep the old format while you refactor.

  2. Identifiers changed

    Strapi says REST responses include both the legacy id and documentId when the header is on, and that GraphQL never exposes the numeric id, so queries should use documentId. Anything that stored or linked by number breaks.

  3. The data migrates automatically, the code does not

    Strapi says built-in data migration scripts run on first startup and that code changes are handled with its upgrade tool, which uses codemods. The Entity Service API is being replaced by the Document Service API, so custom code needs work.

  4. There is no automated way back

    Strapi says there is no automated downgrade. To return to v4 you restore the pre-upgrade database backup and check out the matching code. Without a backup the data migration cannot be undone.

  5. Staying on v4 is also a risk

    Strapi says v4 is no longer supported and that no further v4 updates will be published, so rolling back is a pause, not a destination.

What can I do about it today?

  1. Do not run the upgrade againA second run on a changed database can make recovery harder. Stop and take a copy of the current state first.
  2. Look for a backupAsk your developer and your host whether a database backup from before the upgrade exists, and where.
  3. Keep the current database, even if it is brokenWhatever is in it is the only copy of changes made since the upgrade. Do not delete or overwrite it.
  4. Ask for the exact errorIs it the website, the Strapi admin, or both? An empty page, an error message and a login failure are different problems.
  5. Tell editors to pauseAsk content editors to stop publishing until you know which database is the right one.

When should I bring someone in?

  • The live website is down or empty after the upgrade.
  • There is no backup from before the upgrade.
  • Custom code or plugins stopped working and nobody knows which ones.

How do I handle it?

  1. Secure what existsBoth the current database and any earlier backup are copied away before anything is changed.
  2. Stabilise the website quicklyWhere useful I switch on Strapi's documented v4 compatibility header or setting so the front end can read content again, as a short-term bridge.
  3. Work through the breaking changesUsing Strapi's own list, the front end, custom code and plugins are moved to the new format step by step on a copy.
  4. Rehearse the full upgradeThe upgrade is run on a copy of the production data until it passes, before touching the live system again.
  5. Go live with a tested way backA fresh backup is taken just before, and restoring it has been tried.

The price depends on what I find, so I quote in writing after a short discovery call. Tell me what is happening and I reply within 24 hours.

What do owners ask about this?

Can I go back to Strapi v4?

Strapi says there is no automated downgrade. You restore the pre-upgrade database backup and the matching code. Without a backup that is not possible.

Is Strapi v4 still supported?

Strapi's migration page says v4 is no longer supported and no further v4 updates will be published.

Do I need to rewrite my website?

Not necessarily. The front end has to read the new response format and identifiers. Strapi's compatibility option can help while that is done.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Found a mistake? Tell me.

Next step

Want this off your desk?

Send me a few lines on where things stand. I reply within 24 hours.