WordPress Migration: Audit Attachment Pages and Media URLs Separately

A WordPress migration can pass every blog-post redirect check and still break the images inside those posts. The missing distinction is usually between an attachment page, the HTML page describing a media item, and the media file, the JPEG, PDF or other file the browser actually requests. They need separate rows in the migration inventory and separate acceptance checks.

Keep useful attachment pages or map them deliberately to an appropriate destination. Keep embedded media URLs serving the correct files, directly or through a suitable file-to-file redirect. A redirect that turns an image request into an HTML article is not a successful media migration, even when its final response is 200.

One photograph can have several URLs to preserve

Consider a teaching example: a travel post called “Harbour Walk” contains a photograph called “harbour.jpg.” These paths are illustrative, not a customer migration:

• /harbour-walk/ is the article readers came to read.
• /harbour-walk/harbour/ might be an attachment page, depending on the site's permalink rules.
• The uploads directory, /wp-content/uploads/, followed by 2024/06/harbour.jpg, identifies the original media file.
• The same folder can contain harbour-768x512.jpg, a generated size referenced in responsive image markup.

There may also be a query-based attachment URL, a CDN hostname and older filenames. Do not infer which ones work from the filename alone: request them and record the response type. The HTML attachment page may show a caption or description that is absent from the original image.

A database count of 2,000 attachments does not mean there are only 2,000 public media URLs. Conversely, discovering 10,000 image URLs does not prove that 10,000 distinct originals need to be migrated. Generated sizes and CDN variants explain some of the difference. Keep both an attachment inventory and an observed-URL inventory so that neither count is mistaken for the other.

Check the site's attachment behavior before choosing a rule

WordPress changed the default for new installations in version 6.4. Its attachment-page development note says new sites disable attachment pages and redirect them to the attachment file URL. Existing sites retain attachment pages on upgrade. The controlling option is wp_attachment_pages_enabled; plugins and custom code can also affect what visitors receive.

If WP-CLI is available, this read-only command checks the stored option:

wp option get \
  wp_attachment_pages_enabled

Record the installed WordPress version, that option, active SEO or redirect plugins, and any relevant web-server rules. Then open a sample attachment page and follow its actual redirects. A database option is a useful clue, not proof that a plugin or reverse proxy leaves the response unchanged.

Repeat this check on the destination. Importing an old site's content into a freshly installed WordPress site can introduce a different attachment-page default. Copying a complete database is a different operation from importing posts and media into a new database. Put the intended behavior in the migration plan instead of discovering the difference after cutover.

Build the inventory from requests as well as the Media Library

Start with the media records, the site's rendered pages, existing sitemaps and available access logs. Each source covers a different blind spot. The Media Library identifies originals; rendered HTML exposes the sizes and hosts actually requested; logs may reveal old URLs still used by external pages or bookmarks. A sitemap alone is not a complete asset list.

1. Export attachment records. Preserve the attachment ID, parent ID, original filename, current file URL, attachment-page URL, caption and description. Keep an unchanged copy of the export.
2. Collect embedded URLs. Include src, srcset, linked downloads and gallery links. Inspect relevant CSS background images and any media loaded by gallery scripts too.
3. Add historically requested variants. Use available log history, especially for assets with external referrals. State the date coverage and any missing CDN logs.
4. Classify each row. Mark it as an HTML page, image, document or other resource. Preserve the original scheme, hostname, path and query string until their behavior has been checked.

A useful working sheet has these columns: old URL, resource type, where it was found, intended new URL, intended outcome, first status, final status, final content type, and review note. Keep the intended outcome separate from the observed result. Otherwise a checker can quietly turn “the server did this” into “this is what we wanted.”

An attachment with no parent ID is not necessarily unused. Editors may reuse an image in several posts, paste its URL into a page builder, or use it outside WordPress. Search for actual references before declaring it orphaned.

Decide the destination by what the old URL delivered

Attachment page with useful standalone content

Preserve the page or move it to a genuinely equivalent HTML page. A photography archive with descriptions, credits or comments may have a reason to keep attachment pages. Redirecting every one of those pages to a bare JPEG would discard the surrounding information even if the image survives.

Attachment page that only wraps the file

A redirect to the same media item can be appropriate if the wrapper is intentionally retired. A redirect to a parent article is a separate choice: confirm that the article contains the item and answers the visitor's likely request. Do not assume every upload has one useful parent.

Direct image or download URL

Keep serving the intended file, or redirect to its new equivalent file URL. A browser requesting an image inside <img> cannot display a 200 HTML landing page as that image. A PDF link that ends on the homepage also fails its purpose. Verify the content type and open the actual asset.

Intentionally removed resource with no replacement

Document the removal and return an appropriate 404 or 410 rather than a catch-all homepage redirect. Google's site-move guidance explicitly includes images and downloads in the migration inventory and warns against redirecting unrelated old URLs to a single irrelevant destination.

If filenames and file contents are unchanged, a checksum comparison provides strong transfer-integrity evidence. If the move deliberately changes encoding or dimensions, different hashes are expected; compare the intended rendition, visible content and dimensions instead. Record the transformation so that “different” is not confused with “corrupt.”

Test a redirect and then test what loads

Run a low-concurrency GET-based check against the frozen URL list. Capture the first status and every redirect destination, then the final status and content type. A HEAD-only check can miss response differences. For a practical explanation of the status and redirect-report layer, Guangsuan's guide to checking old URLs, redirect chains and final destinations provides a useful companion to this media-specific inventory.

Use the following four teaching rows to check that your own report distinguishes real success from a green-looking status:

• Old JPEG → new JPEG, final 200 and image content: potentially correct; confirm the picture and intended dimensions.
• Old JPEG → parent article, final 200 and HTML: wrong resource type for an embedded image.
• Old attachment page → same media file, final 200: correct only if retiring that wrapper was the approved mapping.
• Old thumbnail → 404, while the original JPEG works: incomplete migration if published markup or external links still request the thumbnail.

Then test actual pages in a browser at desktop and phone widths. Check the image request selected from srcset, not just the original file. Open gallery items, follow download links, and inspect the network response for a missing rendition. A page may look fine on a high-density desktop but select a broken smaller image on a phone.

Run the check before and after switching traffic. A local hosts-file or origin-only test does not validate the public CDN route. Where you control the old and new hosts, retain both until the public checks establish that the expected paths and files work. Avoid broad filename rewrite rules until representative collisions, case differences and encoded characters have been tested.

Make media acceptance a separate sign-off

The media pass belongs inside the broader Blogswitch migration process, but its result should be explicit. Count tested URLs by resource type, list unresolved destinations, and state the coverage limits of the source exports. Keep the mapping, test date and final report together.

After launch, review new 404s and broken-file requests, rerun the same inventory, and investigate newly discovered old URLs rather than silently adding a blanket redirect. Google recommends retaining migration redirects for at least a year in general; useful links for people may justify longer retention. Technical acceptance proves that the tested URLs deliver their intended resources. Search visibility and traffic need continued observation and cannot be guaranteed by a clean redirect report.