Repository navigation
wp media replace changes the path of the attached file, which potentially breaks links #274
Description
Bug Report
- [ X] Yes, I reviewed the contribution guidelines.
- [ X] Yes, more specifically, I reviewed the guidelines on how to write clear bug reports.
Describe the current, buggy behavior
"wp media replace" uploads a new file, and adjusts the attachment post to reflect the new location of the new file in the upload folder.
The path to the uploaded file therefore changes, even if the attachment id remains the same, and existing links to the file break.
The Gutenberg editor often creates direct links to uploaded files.
It is not a seamless replacement of the attached file.
Describe how other contributors can replicate this bug
- Replace an older media file using "wp media replace", so the new file ends in a different folder in the upload directory.
- Watch links to the old path fail.
Describe what you would expect as the correct outcome
The attached file should be replaced in place, keeping the old path, and if necessary, uploading the file to the old upload folder, as not to create broken image links on the site.
Let us know what environment you are running this on
OS: Linux 6.12.113+deb13-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.12.113-1 (2026-10-15) x86_64
Shell: /usr/sbin/nologin
PHP binary: /usr/bin/php8.4
PHP version: 8.4.27
PHP memory limit: -1
php.ini used: /etc/php/8.4/cli/php.ini
MySQL binary: /bin/mariadb
MySQL version: mariadb from 11.8.6-MariaDB, client 15.2 for debian-linux-gnu (x86_64) using EditLine wrapper
SQL modes: STRICT_TRANS_TABLES,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION
WP-CLI root dir: phar://wp-cli.phar/vendor/wp-cli/wp-cli
WP-CLI vendor dir: phar://wp-cli.phar/vendor
WP_CLI phar path: phar:///usr/local/bin/wp-cli-nightly.phar
WP-CLI packages dir:
WP-CLI cache dir: /var/www/.wp-cli/cache
WP-CLI global config:
WP-CLI project config:
WP-CLI version: 3.0.0-alpha-836ccac
Activity
nathanrice commentedon Nov 3, 2026
This is a valid concern. I've been thinking about it a good bit this morning, and here's what I've come up with so far...
One problem with "replace in place" is that if you're replacing
wp-content/uploads/2023/10/31/halloween.jpgwithhalloween.pngis that the extension mismatch leaves you in the exact same problem as the original bug.So, one possible approach is to do the "replace in place", but only if the extension matches exactly.
If a different extension is detected, we would need to decide which of the following is preferable:
wp media regenerate(link) offers–update-attachment-refsas an optional flag, which will look through all non-revision posts and update references to regenerated media. A similar flag could be added towp media replace, if it doesn't already exist.Option 2 only works in posts (I believe), so references in custom fields, widget, etc., would all be missed.