An unupdated Version of Gutenberg Fatally breaks the site on WordPress 6.1 Autoupdate

[namith.jawahar]

An unupdated Version of Gutenberg Fatally breaks the site on WordPress 6.1 Autoupdate.

I have tested with 14.0.3 of Gutenberg Plugin, need to test with further version to see where this gets fixed.

When sites auto update to WordPress 6.1 and you have an older version of Gutenberg plugin installed the site fatally breaks with an error as follows

Fatal error: Cannot redeclare get_template_hierarchy() (previously declared in ...../wp-includes/block-template-utils.php:1310) in .....c/wp-content/plugins/gutenberg/lib/compat/wordpress-6.1/block-template-utils.php on line 312

Once this happens the users cant access the frontend or the backend to deactivate the plugin.

Solution : Rename or remove and install the latest version of Gutenberg plugin via FTP.

[hellofromTonya]

Hello @namithjawahar,

Welcome back to WordPress Core Trac! Thank you for reporting this issue.

Doing some backtracing in the Gutenberg repository:

• Gutenberg 13.9.0 added the get_template_hierarchy() function but did not protect it from a conflict with Core.
• Gutenberg 14.1.0+ added the protective guard (i.e. wrapped it with function_exists().

In WordPress 5.8, ​a function was added to deactivate an older incompatible plugin. This function was updated in WP 5.9. It was not updated in WP 6.1.

For WP 6.1, a fix is to update the Gutenberg version number from 11.9 to 14.1. This change should avoid a fatal error for anyone updating to 6.1.1+ with an older version the Gutenberg plugin.

Moving this into 6.1.1 milestone.

Using the same strategy during WP 5.9 (see changeset https://core.trac.wordpress.org/changeset/52199):

• Renames the update function for WP 6.1
• Changes the Gutenberg version number from 11.9 to 14.1

Why? Gutenberg plugin versions less than 14.1.0 are not compatible with WP 6.1, especially GB 13.9.0 to 14.0.x versions which will cause a fatal error.

Trac ticket: https://core.trac.wordpress.org/ticket/56985

[hellofromTonya]

Some history for the context and the commit messages:

• [54269] introduced the new function into Core during the WP 6.1 cycle.
• [51180] introduced the process of deactivating incompatible versions of the plugin (in WP 5.8).
• [51266] notified users of the deactivated plugin during the upgrade.
• [52165] and [52199] updated for its incompatible versions (in WP 5.9).

[namith.jawahar]

Is there a way to prevent the auto update from running with this combo via the update notification REST API.

​http://api.wordpress.org/core/version-check/

[azaozz]

Replying to namith.jawahar:

Is there a way to prevent the auto update from running

Thinking the proper way to fix this kind of errors is to not load the old version of Gutenberg in the new version of WP. The block editor in the new WP would have the functionality from the old Gutenberg plugin anyway, and probably a lot more.

[namith.jawahar]

Replying to azaozz:

Updating the plugin fixes the issue and is the straight forward way to prevent it from happening when you are in control. The problem is auto updates which happen without user intervention. It would be good if we have a system of verifying very popular incompatible plugins via the update notification API itself so that something like this can be prevented in future too.

The solution would be simple and can be rolled out even after a version is released if it can be implemented via the API : If there is an incompatible plugin don't do / offer an auto update.

[azaozz]

Replying to namith.jawahar:

Updating the plugin fixes the issue and is the straight forward way to prevent it from happening

Not exactly :)

The newer version of Gutenberg would usually require newer version of WP. So you will not be able to update Gutenberg if you are running an older version of WP, usually 2-3 versions behind.

It would be good if we have a system of verifying very popular incompatible plugins

Perhaps, but that usually is not known before a new WP version is released. I.e. plugins have minimum required version, but don't have maximum allowed version of WP.

The solution would be simple and can be rolled out even after a version is released if it can be implemented via the API : If there is an incompatible plugin don't do / offer an auto update.

Not sure that would be a good solution :)

The core team will have to test how compatible old versions of some plugins are before each WP release, and to be able to detect less obvious incompatibilities.

That is usually not needed for any plugin as core is pretty good in maintaining forward compatibility, and plugin authors are pretty good in updating their plugins. The only exception is Gutenberg as its code is merged to core. Then there's the question of how namy: 100, 200, 500 "top plugins" would have to be tested, and how far back: 1 year, 2 years, 5 years... Seems this will quickly become an impossibly big task :)

Also, Gutenberg in not a standard WP plugin. It is part of core that is being developed separately and released as a plugin for early preview/testing. That's the reason there is a tight correlation between the Gutenberg and WP versions.

[hellofromTonya]

Test Instructions

Steps to Reproduce

• Step 1: Install WP 6.0.3
  • Using WP-CLI

    wp core update --version=6.0.3 --force
    

  • Using the ​Core Rollback plugin

• Step 2: Install Gutenberg v 13.9.0
  • Using WP-CLI

    wp plugin install gutenberg --version=13.9.0 --force
    

  • Using the ​wp.org plugin page:
    • Go here ​https://wordpress.org/plugins/gutenberg/advanced/
    • Scroll down to the version select field
    • Select 13.9.0
    • Click/trigger the Download button
    • Install zip file via the upload UI in your local test site: Plugins > Add New > Upload Plugin

• Step 3: Activate Gutenberg plugin
• Step 4: Update to WP 6.1.0
  • Using WP-CLI

    wp core update --version=6.1.0 --force
    

    • Then refresh the Plugins page. 🐞 Bug occurs with a fatal error.
  • Using WordPress Updates UI
    • In the admin area, go to Dashboard > Updates
    • Click/trigger the Update to version 6.1 button.
    • Update starts and then fails. 🐞 Bug occurs with a fatal error.
• Step 5: Cleanup by deleting the Gutenberg plugin folder.

Notes:

• Repeat the tests using Gutenberg version 14.0.3. Same 🐞 fatal error.
• Repeat the tests using Gutenberg version 14.1.0. ✅ Update succeeds with no fatal error.

Steps to Prepare WP zip file with fix:

• Step 1: Download WP 6.1.0 ​https://wordpress.org/download/
• Step 2: Unzip the download file
• Step 3: Merge the changes from the PR ​https://github.com/WordPress/wordpress-develop/pull/3559
• Step 4: Rezip the folder

Steps to Test the Fix

See how to do each step above.

• Step 1: Install WP 6.0.3
• Step 2: Install Gutenberg v 13.9.0
• Step 3: Activate Gutenberg v 13.9.0
• Step 4: Update to WP 6.1.x using the zip file

  wp core update --version=6.1 --force ../path/to/wordpress.zip
  

• Step 5: Go to the Plugins UI.
  • Expected: Gutenberg plugin is deactivate ✅
  • Expected: No fatal error ✅

[hellofromTonya]

Test Report

Env

• OS: macOS
• Browser: Firefox
• Localhost: WP Local
• Update method: wp-cli

Reproduce Fatal Error

Using Gutenberg v 13.9.0:

• Step 1:

Testing with the Fix

Note: I copied the wordpress.zip file to /Local/wp61/app/ folder.

Test Fix with Gutenberg v14.0.3

• Step 1: Rollback to WP 6.0.3

  wp core update --version=6.0.3 --force
  

• Step 2: Install and active Gutenberg v 13.9.0

  wp plugin install gutenberg --version=13.9.0 --activate
  

• Step 3: Install wordpress.zip with the fix

  wp core update --version=6.1 ../wordpress.zip
  

• Step 4: Verify Gutenberg plugin deactivated with no fatal error. Go to and refresh the Plugins UI page. Results:
  • Gutenberg plugin did deactivate ✅
  • No fatal error ✅

Test Fix with Gutenberg v14.0.3

• Step 1: Rollback to WP 6.0.3

  wp core update --version=6.0.3 --force
  

• Step 2: Install and active Gutenberg v 14.0.3

  wp plugin install gutenberg --version=14.0.3 --activate
  

• Step 3: Install wordpress.zip with the fix

  wp core update --version=6.1 ../wordpress.zip
  

• Step 4: Verify Gutenberg plugin deactivated with no fatal error. Go to and refresh the Plugins UI page. Results:
  • Gutenberg plugin did deactivate ✅
  • No fatal error ✅

Test Fix with Gutenberg v14.1.0

• Step 1: Rollback to WP 6.0.3

  wp core update --version=6.0.3 --force
  

• Step 2: Install and active Gutenberg v 14.1.0

  wp plugin install gutenberg --version=14.1.0 --activate
  

• Step 3: Install wordpress.zip with the fix

  wp core update --version=6.1 ../wordpress.zip
  

• Step 4: Verify Gutenberg plugin does NOT deactivate. Go to and refresh the Plugins UI page. Results:
  • Gutenberg plugin is activated, ie did not deactivate ✅
  • No fatal error ✅

Results

• Can reproduce the bug 🐞
• With the fix:
  • Gutenberg v13.9.0:
    • Gutenberg plugin did deactivate ✅
    • No fatal error ✅
  • Gutenberg v14.0.3:
    • Gutenberg plugin did deactivate ✅
    • No fatal error ✅
  • Gutenberg v14.1.0:
    • Gutenberg plugin did not deactivate ✅
    • No fatal error ✅

​PR 3559 fixes the fatal error and works as expected ✅

I've tested this PR. See the Test Report.

Results:

• Gutenberg v 13.9.0: plugin deactivates during the update ✅
• Gutenberg v 14.0.3: plugin deactivates during the update ✅
• Gutenberg v 14.1.0: plugin stays activated (does not deactivate) during the update ✅

This PR fixes the issue.

@desrosj The renaming follows what happened in WP 5.9. When upgrading to the current version in trunk or the branch, the older versions no longer matter. Why? This change is not being backported to the older branches.

The renaming and removal of the older function was discussed in the 5.9 ticket. Note a comment from @SergeyBiryukov https://core.trac.wordpress.org/ticket/54405#comment:16

This is an interesting precedent as we don't generally remove functions, but it seems fine in this case, and makes sense to me too.

Ah, yes,. I see that now.

Sorry, I edited my comment above right after sending to include the following:

Even though it's private, the practice used in the areas of Core related to upgrades is to leave things in place for a historical and chronological reference.

I think this would still be great to have, but since it's not currently the practice for this specific part, then this is _probably_ OK.

What about a compromise of removing the version from the function name and using the docblock (maybe @since tags) to track this history?

* @since 5.9 The minimum compatible version of Gutenberg is now 13.1.
* @since 6.1 The minimum compatible version of Gutenberg is now 14.1.
etc..

This makes it easier in the future (only the version number needs to be changed), and it also preserves a historical record.

@desrosj Some questions:

• Are you also wanting to loop in the code from _upgrade_440_force_deactivate_incompatible_plugins() into this new _upgrade_deactivate_incompatible_plugins() function?
• Should we also remove _upgrade_440_force_deactivate_incompatible_plugins() and _upgrade_590_force_deactivate_incompatible_plugins() with this fix?

Maybe. I think that deserves a larger discussion though. We've demonstrated that though rare, these are not one off exceptions now (REST API, Gutenberg, etc.), so I think it makes sense to think about how to make this easier overall.

@desrosj We wrote at the same time 🤣 Disregard my last comment.

Maybe we could look at revisiting reworking this area of code in the next major cycle to incorporate your idea of modeling after the $_new_bundled_files and $_old_files. In doing so, this fix for this specific fatal error doesn't introduce any new risks and avoids scope creep.

The patch LGTM too, good job!

As discussed before, ideally this functionality will be in the plugins. It is not that hard to add a condition (or two) in a plugin's bootstrap to check the current WP version and stop loading the rest of the plugin (and show a warning, etc.) if it is deemed unsupported (too new).

Of course some plugins would not want to do that as they are not updated frequently, and limiting the "lifetime" of current plugin version may not be desirable for the authors. However Gutenberg and other frequently updated plugins would be quite safer if they had such code.

Of course some plugins would not want to do that as they are not updated frequently, and limiting the "lifetime" of current plugin version may not be desirable for the authors. However Gutenberg and other frequently updated plugins would be quite safer if they had such code.

I don't think it's that straightforward. In order for this to work, plugins need to know in advance which versions will be incompatible because even if the code is in a plugin release, there is no guarantee that site owners update that plugin.

It's far more likely Core will update now that auto-updates for major releases are enabled by default. I think it's reasonable to have a small handful of exceptions for plugins built by Core team members and contributors. With the request for more canonical and feature plugins to build out and test new features, it's likely this problem will be encountered again soon.

In order for this to work, plugins need to know in advance which versions will be incompatible because even if the code is in a plugin release, there is no guarantee that site owners update that plugin.

Right. Such cutout would be more of an estimate. It also sets a hard "Must update for compatibility with WP version x.y.z" requirement. So basically implementing a "Compatible up to" functionality would mean each plugin version will have a fixed lifecycle length.

I'd think that would be very welcome for Gutenberg as the code from the plugin is added to core regularly. Other frequently updated plugins would probably find it useful too.

I think it's reasonable to have a small handful of exceptions for plugins built by Core team members and contributors.

I'm not against having this function in core. It is a useful safeguard, and renamed as in this patch it looks pretty good. Just thinking it would be better for plugins to "manage" their compatibility themselves.

In order for this to work, plugins need to know in advance which versions will be incompatible because even if the code is in a plugin release, there is no guarantee that site owners update that plugin.

Right. Such cutout would be more of an estimate. It also sets a hard "Must update for compatibility with WP version x.y.z" requirement. So basically implementing a "Compatible up to" functionality would mean each plugin version will have a fixed lifecycle length.

I'd think that would be very welcome for Gutenberg as the code from the plugin is added to core regularly. Other frequently updated plugins would probably find it useful too.

I think it's reasonable to have a small handful of exceptions for plugins built by Core team members and contributors.

I'm not against having this function in core. It is a useful safeguard, and renamed as in this patch it looks pretty good. Just thinking it would be better for plugins to "manage" their compatibility themselves.

[hellofromTonya]

All feedback is addressed and 2 LGTM. ​PR 3559 is ready for commit. Prepping the commit now.

[hellofromTonya]

In 54789:

Update/Install: Deactivate Gutenberg plugin version older than 14.1.

Resolves a fatal error due to get_template_hierarchy() due to incompatible older Gutenberg versions.

[54269] introduced this new function for 6.1. The function was introduced in Gutenberg 13.9.0. However, it was not guarded to protect the plugin from when the function was loaded in Core. Gutenberg 14.1.0 added the function_exists() guard to protect the plugin from the fatal error.

Minimum compatible version:
This commit changes the Gutenberg minimum compatible version number to 14.1. For versions older than 14.1, the plugin will deactivate when upgrading Core to 6.1 or newer.

Function rename:
Past commits renamed the upgrade function by changing Core's version number. This commit renames the function to be generic, i.e. _upgrade_core_deactivate_incompatible_plugins() and adopts the @since [reason] strategy to track historical changes to the function.

Follow-up to [54269], [52199], [52166], [52165], [51180].

Props namithjawahar, hellofromTonya, azaozz, desrosj, ironprogrammer.
Fixes #56985.

Committed via https://core.trac.wordpress.org/changeset/54789. Thank you everyone for your contributions!

[hellofromTonya]

Reopening to backport [54789] to the 6.1 branch ahead of 6.1.1 RC.

[hellofromTonya]

In 54790:

Update/Install: Deactivate Gutenberg plugin version older than 14.1.

Resolves a fatal error due to get_template_hierarchy() due to incompatible older Gutenberg versions.

[54269] introduced this new function for 6.1. This function was introduced in Gutenberg 13.9.0. However, it was not guarded to protect the plugin from when the function was loaded in Core. Gutenberg 14.1.0 added the function_exists() wrapper to protect the plugin from the fatal error.

Minimum compatible version:
This commit changes the Gutenberg minimum compatible version number to 14.1. For versions older than 14.1, the plugin will deactivate when upgrading Core to 6.1 or newer.

Function rename:
Past commits renamed the upgrade function by changing Core's version number. This commit renames the function to be generic, i.e. _upgrade_core_deactivate_incompatible_plugins() and adopts the @since [reason] strategy to track historical changes to the function.

Follow-up to [54269], [52199], [52166], [52165], [51180].

Props namithjawahar, hellofromTonya, azaozz, desrosj, ironprogrammer.
Merges [54789] to the 6.1 branch.
Fixes #56985.

[hellofromTonya]

The fix has now been merged into trunk and backported to the 6.1 branch. It will ship in WP 6.1.1.

Thank you again @namithjawahar for reporting this issue 🌟
Thank you everyone for your contributions 🌟