Theme update fails, creates duplicate directory after incorrect plugin update attempt

[leemon]

When attempting to update an existing theme (e.g., my-theme) via ZIP upload using the WordPress admin installer, an issue arises if a prior, incorrect update attempt was made through the plugin installer.

Steps to reproduce:

1. Have an existing theme installed (e.g., my-theme).
2. Prepare a ZIP file of an updated version of my-theme.
3. Navigate to Plugins > Add New > Upload Plugin.
4. Attempt to upload the theme ZIP file.
5. WordPress correctly displays the error: "The package could not be installed. No valid plugins were found. Plugin installation failed."
6. Navigate to Appearance > Themes > Add New > Upload Theme.
7. Attempt to upload the same theme ZIP file that was used in step 4.
8. Expected behavior: WordPress should overwrite the existing wp-content/themes/my-theme directory with the contents of the uploaded ZIP file, effectively updating the theme.
9. Actual behavior: Instead of overwriting, WordPress creates a new directory named wp-content/themes/my-theme-1 and installs the updated theme there. The original wp-content/themes/my-theme directory remains untouched.
10. Subsequent attempts to update the theme through the theme installer will continue to create new directories, making it impossible to update the theme correctly.

This behavior suggests that the failed plugin installation attempt leaves a residual state or flag that incorrectly influences subsequent theme update attempts, preventing the proper overwrite of the existing theme directory. This can lead to a cluttered themes directory and a broken update mechanism for the affected theme.

I'm using WP 6.8.2, but this behavior affects previous versions, too.

[leemon]

The header of the my-theme theme is:

/*
Theme Name: My Theme
Theme URI:
Update URI: false
Author: An author
Author URI: https://mytheme.com/
Description: My theme is a simple theme.
Version: 1.0
Requires at least: 6.8
Tested up to: 6.8
Requires PHP: 7.4
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Tags: block-styles, blog, custom-colors, custom-logo, custom-menu, e-commerce, footer-widgets, left-sidebar, photography, portfolio, right-sidebar, theme-options, translation-ready, threaded-comments, two-columns
Text Domain: my-theme
Domain Path: /languages

This theme, like WordPress, is licensed under the GPL.
*/

[leemon]

Linking this somewhat related ticket: #29798

[krupajnanda]

Reproduction Report

Description

This report validates that the issue can not be reproduced. ❌

Environment

• WordPress: 6.8.2
• PHP: 8.2.15
• Server: nginx/1.29.0
• Database: mysqli (Server: 8.4.5 / Client: mysqlnd 8.2.15)
• Browser: Chrome 138.0.0.0
• OS: macOS
• Theme: Hello Biz 10.0
• MU Plugins: None activated
• Plugins:
  • Test Reports 1.2.0

Actual Results

1. Error condition does not occur. ❌

Additional Notes

• I tried the exact steps to reproduce the issue but I am unable to replicate the same at my end. I don't see the folders keep getting added under the mentioned scenario.

It prompts the user that the destination folder already exists! Then user needs to wisely choose the action.

Supplemental Artifacts

Add as Attachment

[Later edit] The plugins screen version is different in uploaded screenshot but I have tested the same at theme and plugin so ignore the version.

[khushdoms]

Reproduction Report

❌ I am unable to reproduce the issue as described.

Environment:

• WordPress: 6.8.1
• PHP: 8.0.26
• Server: Apache/2.4.54 (Win64) PHP/8.0.26 mod_fcgid/2.3.10-dev
• Database: mysqli (Server: 8.0.31 / Client: mysqlnd 8.0.26)
• Browser: Chrome 138.0.0.0
• OS: Windows 10/11
• Theme: Twenty Twenty-Five 1.2
• Plugins:
  • Test Reports 1.2.0
  • WP Rollback 2.0.7

Steps I Tried:

1. Installed a theme (e.g., "Twenty Twenty-Five 1.0").
2. Uploaded the updated theme ZIP Twenty Twenty-Five 1.2.

✅ Result: WordPress correctly showed "Destination folder already exists" and did not create a duplicate directory.

Notes:

• I double-checked the wp-content/themes/ folder and no duplicate like "twentytwentyfive-1" was created.
• This may be environment-specific or a caching issue in the original report.

[khushdoms]

Uploaded Updated Theme without face Error

[leemon]

Replying to khushdoms:

Reproduction Report

❌ I am unable to reproduce the issue as described.

Environment:

• WordPress: 6.8.1
• PHP: 8.0.26
• Server: Apache/2.4.54 (Win64) PHP/8.0.26 mod_fcgid/2.3.10-dev
• Database: mysqli (Server: 8.0.31 / Client: mysqlnd 8.0.26)
• Browser: Chrome 138.0.0.0
• OS: Windows 10/11
• Theme: Twenty Twenty-Five 1.2
• Plugins:
  • Test Reports 1.2.0
  • WP Rollback 2.0.7

Steps I Tried:

1. Installed a theme (e.g., "Twenty Twenty-Five 1.0").
2. Uploaded the updated theme ZIP Twenty Twenty-Five 1.2.

✅ Result: WordPress correctly showed "Destination folder already exists" and did not create a duplicate directory.

Notes:

• I double-checked the wp-content/themes/ folder and no duplicate like "twentytwentyfive-1" was created.
• This may be environment-specific or a caching issue in the original report.

You need to try to update the theme using the PLUGIN installer first. And after that, using the THEME installer.

[krupajnanda]

@leemon Yes, I did change in version and then created the zip file and used the same file to reupload at plugins and themes page. But could not encounter the issue.

[iamshashank]

Reproduction Report

Description

❌ This report validates that the issue cannot be reproduced.

Environment

• WordPress: 6.8.2
• PHP: 8.2.27
• Server: nginx/1.26.1
• Database: mysqli (Server: 8.0.35 / Client: mysqlnd 8.2.27)
• Browser: Firefox 140.0
• OS: macOS
• Theme: Twenty Twenty-Five 1.2
• MU Plugins: None activated
• Plugins:
  • Test Reports 1.2.0

Actual Results

1. ❌ Error condition does not occur.

Additional Notes

• I followed the same steps for reproducing the issue, but the theme installed successfully without creating a new directory.
• First i tried uploading the theme in Upload Plugin
• Then I uploaded the same theme in Upload Theme
• It uploaded successfully and overwritten the existing theme.

[SirLouen]

It appears that we already have a ton of reports and no one can reproduce

@leemon can you provide a screencast showing what you are actually doing, and it will be easier to replicate?

[leemon]

I've been testing this issue further, and it appears the behavior I described is related to the structure of the theme's ZIP file.

I tested the reproduction steps with a default theme (like Twenty Twenty-One), and it does not exhibit the bug. When attempting the incorrect plugin update and then the correct theme update, Twenty Twenty-One updates as expected, overwriting the existing theme folder.

The key difference I found is how the ZIP files are structured:

• The Twenty Twenty-One ZIP file contains a root folder named twentytwentyone, and all the theme files are inside that folder.
• My custom theme's ZIP file, which initially caused the issue, had its theme files directly at the root of the ZIP, not inside any containing folder.

When I re-zipped my custom theme's files so that they were inside a folder named my-theme (matching the theme's slug) at the root of the ZIP, the issue disappeared. Now, after an incorrect plugin update attempt, the subsequent theme update works as expected, correctly overwriting the wp-content/themes/my-theme directory.

It seems that the presence of a containing folder within the theme ZIP is crucial for WordPress to correctly handle the update process, especially after a failed attempt in the wrong installer. This might indicate an expectation in the installer's logic that anticipates a single root directory within the uploaded ZIP for themes.

[leemon]

Given that this issue seems to be resolved by ensuring the theme ZIP file has a single root folder named after the theme slug (e.g., my-theme/ containing all theme files), I'm wondering if this is a documented requirement for theme ZIP file structure for updates, especially when using the admin installer.

I've looked through some of the Theme Handbook and developer resources, but I haven't explicitly found a section that outlines this specific packaging requirement for ZIP files to ensure smooth updates, particularly in scenarios where a previous, incorrect installation attempt might have occurred.

If this is indeed a standard or best practice, it would be helpful to have it clearly documented to prevent similar issues for other theme developers and users. Could someone point me to any existing documentation that covers this, or consider adding it if it's not currently present?

Thanks!

[SirLouen]

Replying to leemon:

Given that this issue seems to be resolved by ensuring the theme ZIP file has a single root folder named after the theme slug (e.g., my-theme/ containing all theme files), I'm wondering if this is a documented requirement for theme ZIP file structure for updates, especially when using the admin installer.

True, its something very well known, but I have not found a place that explicitely states that: all the docs take for granted that, like plugins, themes are self contained in its own folder (and not the files directly in the root of the compressed filed)

I suggest you to propose this in the docs github for ​https://github.com/WordPress/HelpHub/issues

Post there your concern and if you want, post here the link to that.

[leemon]

Link to the docs github: ​https://github.com/WordPress/HelpHub/issues/358

[SirLouen]

Thanks @leemon its time to close this now.