Fix Broken Image Links in WordPress WooCommerce Stores

Introduction

Fixing broken image links in WordPress for WooCommerce stores in 2026 usually means tracing one of four layers: the attachment record in MySQL, the file inside `wp-content/uploads`, the generated thumbnail metadata, or the delivery path through a CDN or proxy. On product-heavy stores, a single break can hit category pages, product galleries, structured data, and conversion rates at the same time.

This guide assumes a live WooCommerce environment where product images, variation thumbnails, or category visuals are returning 404 errors, loading as empty placeholders, or pointing to old domains after a migration. The workflow below is designed for technically competent site owners, developers, and store operators running modern WordPress stacks on PHP 8.2 or 8.3. It also fits stores using image optimization layers such as Media Optimizer, cleanup workflows like Unused Media Cleaner, and broader performance reviews from Web Image Performance In 2026.

Prerequisites

What you need and why: broken image links are rarely fixed safely without verifying versions, file ownership, and backup access first.

• WordPress 6.8 or later
• WooCommerce 10.x
• PHP 8.2 or PHP 8.3
• MySQL 8.0 or MariaDB 10.6+
• SSH or terminal access for the web server user
• WP-CLI 2.10+ installed and available in the site root
• A current database backup and uploads backup
• Access to the active CDN, reverse proxy, or image optimization layer if one is in front of WordPress

Component	Recommended Version	Why It Matters
WordPress	6.8+	Attachment handling and image regeneration behavior can differ across major versions
WooCommerce	10.x	Product gallery and variation image handling must match current schema
PHP	8.2 or 8.3	Required for current plugin compatibility and predictable WP-CLI behavior
WP-CLI	2.10+	Needed for media audits, regeneration, and search-replace checks

Installation And Setup

What you should prepare and why: you want a clean audit path before touching metadata, regenerating thumbnails, or editing URLs.

First, move into the WordPress document root as a non-root deployment user such as `www-data`, `deploy`, or your host account.

pwd
ls -lah
wp core version
wp plugin list --status=active

Expected output should confirm the correct site root and show WooCommerce as active.

6.8.1
+----------------------+--------+-----------+---------+
| name                 | status | update    | version |
| woocommerce          | active | none      | 10.x.x  |
+----------------------+--------+-----------+---------+

Next, inspect a known broken image URL from a product page and compare it against the attachment record.

wp post list --post_type=attachment --fields=ID,post_title,guid --format=table | head -20

If you already know the attachment ID, pull its metadata directly.

wp post meta get 1234 _wp_attached_file
wp post meta get 1234 _wp_attachment_metadata --format=json

On Linux-based WordPress hosting, the expected file location usually maps like this:

ls -lah wp-content/uploads/2026/04/

If your store has had media bloat or accidental cleanup, it is worth reviewing how image files are managed before restoring anything. These two references are useful when the root cause turns out to be optimization or cleanup side effects: 9 Free WordPress Media Optimization Plugins Compared and Unused Media Cleaner.

Configuration

What to verify and why: many broken image links are configuration issues, not missing files.

Start with the core URL settings.

wp option get home
wp option get siteurl

If the domain changed recently, check whether attachments still reference the old hostname.

wp db query "SELECT ID, guid FROM wp_posts WHERE post_type='attachment' AND guid LIKE '%old-domain.com%' LIMIT 20;"

On stores behind Cloudflare, Bunny, a subdomain CDN, or a proxy rewrite, confirm the expected upload base path in WordPress. Broken paths often appear after moving from local uploads to a CDN origin path such as `/wp-content/uploads/` versus `/content/uploads/`.

Check whether custom upload constants are defined.

grep -nE "UPLOADS|WP_CONTENT_URL|WP_HOME|WP_SITEURL" wp-config.php

Typical correct cases:

• No custom `UPLOADS` constant unless the store deliberately uses a non-standard upload directory
• `WP_HOME` and `WP_SITEURL` point to the canonical production domain
• CDN rewrite plugins are configured to rewrite URLs consistently for original files and generated sizes

If permissions are wrong, WordPress may fail to generate derivative images even when the original upload exists.

find wp-content/uploads -type d | head -5 | xargs -I{} stat -c "%a %U:%G %n" {}
find wp-content/uploads -type f | head -5 | xargs -I{} stat -c "%a %U:%G %n" {}

A practical baseline for many Ubuntu and Debian stacks is:

• Directories: `755`
• Files: `644`
• Owner/group aligned with the PHP-FPM or web server process

If your store uses image automation or alt-text workflows that create or rewrite media assets, keep those plugin paths consistent with the current domain and uploads structure. Related product pages and tools on Flux Plugins include AI Media Alt Creator and Alt Text Checker.

Usage And Execution

What to do and why: the safest repair flow is to prove whether the problem is a missing file, bad metadata, or a bad URL, then fix only that layer.

Audit The Broken Attachment

Look up one broken image from the browser, then inspect its attachment path.

wp db query "SELECT ID, post_title, guid FROM wp_posts WHERE guid LIKE '%broken-filename%' OR post_title LIKE '%broken-filename%' LIMIT 10;"

Then verify the stored relative file path.

wp post meta get 1234 _wp_attached_file

You should see something like:

2026/04/product-photo.webp

Now confirm whether that file exists on disk.

test -f wp-content/uploads/2026/04/product-photo.webp && echo "exists" || echo "missing"

Restore Or Repoint Missing Files

If the file is missing, restore it from backup or copy it from the old server before regenerating thumbnails.

rsync -avz oldhost:/var/www/example.com/public_html/wp-content/uploads/2026/04/product-photo.webp wp-content/uploads/2026/04/

If the file exists under a different name after migration, update the attachment path carefully.

wp post meta update 1234 _wp_attached_file '2026/04/product-photo-restored.webp'

Regenerate Thumbnails

If the original file exists but product thumbnails are broken, regenerate metadata and derivative sizes.

wp media regenerate 1234 --yes

For a broader repair on a medium-sized catalog:

wp media regenerate --only-missing --yes

Expected output:

Found 1 image to regenerate.
Success: Regenerated 1 of 1 images.

Fix Old Domain Or Mixed Upload URLs

If product pages still point to a retired domain or staging hostname, run a dry check first.

wp search-replace 'https://staging.example.com' 'https://store.example.com' --skip-columns=guid --dry-run

If the preview looks correct, run it for real.

wp search-replace 'https://staging.example.com' 'https://store.example.com' --skip-columns=guid
wp cache flush

Use caution with `guid`. In most cases, do not bulk rewrite attachment `guid` unless you have a specific migration reason and understand the downstream effects.

Verify WooCommerce Product Associations

Sometimes the image exists, but the product is linked to a deleted attachment ID. Check the product thumbnail and gallery values.

wp post meta get 5678 _thumbnail_id
wp post meta get 5678 _product_image_gallery

If the product references a dead attachment ID, replace it with a valid one.

wp post meta update 5678 _thumbnail_id 1234

Recheck Frontend Delivery

After repairs, test the image URL directly and from a product page.

curl -I https://store.example.com/wp-content/uploads/2026/04/product-photo.webp

A healthy response usually returns `200 OK` and an image content type.

HTTP/2 200
content-type: image/webp

Troubleshooting

What to inspect and why: when the normal repair flow fails, the remaining issues are usually cache, metadata corruption, or offloaded-media rules.

404 From CDN But 200 From Origin

If the origin file loads but the CDN URL fails, the edge layer is serving a stale path or missing asset.

Check these points:

• Purge the single broken URL and then the image path prefix if needed
• Confirm the CDN origin still maps to the live `wp-content/uploads` directory
• Verify any WebP or AVIF rewrite rules still point to real files
• Rebuild transformed variants if your optimization plugin generates alternate formats

A common 2026 quirk is that CDN rules may cache now-deleted derivative filenames even after the original file is restored.

Image Exists But Thumbnails Stay Broken

This usually means `_wp_attachment_metadata` is incomplete, corrupted, or built against an older editor stack.

Inspect the metadata payload.

wp post meta get 1234 _wp_attachment_metadata --format=json

If the `sizes` array is empty or references nonexistent filenames, regenerate the image again after confirming write permissions in the target uploads folder.

Product Points To Deleted Attachment ID

WooCommerce can keep `_thumbnail_id` or gallery references after aggressive media cleanup, import rollbacks, or partial database restores.

Verify the attachment post still exists.

wp post get 1234 --field=post_type

If no attachment post is returned, assign a valid attachment ID to the product and resave the product page or update it through WP-CLI.

Conclusion

Fixing broken image links in WordPress for WooCommerce stores is mostly a matter of isolating the failing layer instead of blindly regenerating everything. In practice, you want to verify the attachment record, confirm the physical file, rebuild derivative sizes, and then clear any CDN or cache path still serving stale URLs. That sequence prevents unnecessary database edits and reduces the chance of breaking healthy media entries.

For stores with lots of imported products or automated image workflows, build verification into your routine: test direct image URLs, spot-check category thumbnails, and review uploads after migrations or cleanup jobs. If you also manage optimization, alt-text, or media lifecycle tooling, the related Flux resources linked above can help prevent the same class of image breakage from returning.