Back to Community
Home / Community / Plugin → Better search replace

Troubleshooting Broken Images After Using Better Search Replace

19 threads Sep 9, 2025 Plugin → Better search replace

Content

Better Search Replace is a powerful tool for performing database operations on a WordPress site. A common task is updating URLs, such as moving a site to HTTPS or changing a domain. However, users sometimes report that their images break or disappear from the Media Library after running a search and replace. This guide explains why this happens and the most effective ways to resolve it.

Why Do Images Break After a Search/Replace?

The primary cause of broken images is that the search and replace operation inadvertently modified serialized data in the database. WordPress stores some data, like image metadata and certain plugin settings, in a serialized format. This format includes the length of the stored strings. If you search for one string and replace it with another of a different length (e.g., changing http:// to https:// adds one character), the serialized string lengths become incorrect, corrupting the data. This corruption often manifests as blank images in the Media Library because WordPress can no longer correctly read the image's file path or URL.

Common Solutions and Troubleshooting Steps

1. Restore from a Backup (The Safest Option)

As highlighted in the sample threads, the developers of Better Search Replace state that the plugin does not create a log of changes or have an undo feature. The single most reliable way to revert a problematic search/replace is to restore your site from a backup that was created immediately before you ran the operation. Always ensure you have a recent backup before making any database changes.

2. Identify and Manually Repair Corrupted Data

If a backup is not available, you will need to identify the corrupted records and fix them manually. This often involves the wp_postmeta table.

  • Find the Post ID: In your WordPress Media Library, click on a broken image. In the URL of the attachment details page, you will find a parameter like post=123. This number is the attachment's Post ID.
  • Inspect the Database: Use a database management tool like phpMyAdmin. Run a query to look at the records in the wp_postmeta table for the Post ID you found (e.g., SELECT * FROM wp_postmeta WHERE post_id = 123).
  • Look for Corrupted Serialized Data: Pay special attention to the _wp_attachment_metadata meta_key. The corresponding meta_value might look like garbled text if it's corrupted. You may need to manually update this value or other related fields with the correct, uncorrupted URL.

3. Check Other Locations for Hardcoded URLs

Sometimes, the issue isn't corruption but that the URL exists somewhere the plugin couldn't reach. Common culprits include:

  • Custom CSS: As one user discovered, an old HTTP URL was hardcoded in their theme's Custom CSS section.
  • Theme or Plugin Files/Option Values: URLs can be stored in theme configuration files or in the options table within serialized data that wasn't selected during the search/replace.
  • Third-Party Plugins: Plugins like WooCommerce or offload media plugins may store URLs in custom tables or in a different format. A user trying to update WooCommerce download file URLs found the plugin's method might not work for that specific data.

4. Use a Specialized Plugin for SSL/HTTPS Transition

For the specific case of moving a site from HTTP to HTTPS, a general search/replace can be risky. Several users successfully resolved mixed content warnings (the grey padlock) by using a dedicated plugin like SSL Insecure Content Fixer. These plugins dynamically rewrite insecure URLs on the fly, often providing a more complete and less error-prone solution than a direct database replacement.

Best Practices to Prevent Issues

  • Always Backup First: This cannot be overstated. Never run a search/replace without a full database backup.
  • Be Specific with Strings: Use the full, absolute path (e.g., http://olddomain.com/wp-content/uploads/) instead of a relative one (e.g., /wp-content/uploads/) to minimize the chances of unintended matches and corruption.
  • Test on a Staging Site: If possible, perform the search/replace on a copy of your live site first to identify any potential problems.
  • Select Tables Carefully: Understand which tables you are searching. Selecting all tables can sometimes cause issues. The core tables for content are typically wp_posts and wp_postmeta.

While Better Search Replace is an excellent tool, it operates directly on the database, which requires caution. Understanding these common pitfalls will help you effectively troubleshoot and resolve issues with broken images.

Related Support Threads Support