Skip to content

[00] Subset Redirects, User guide

Redirect old URLs after a migration

Last updated

Save the old site's URL list, log the 404s after the move, import redirects for them in bulk, and test each one before you trust it.

To redirect old URLs after a migration, save a list of every URL the old site served before you move it. After the move, check which of those URLs now return 404, import a redirect for each one from a CSV file, and keep the 404 log running to catch the ones your list missed. Then test every redirect before you make it permanent.

1. Save the old URL list before you migrate

Once the new site is live, the old URLs only exist in search results, bookmarks and other people’s links. Save them while the old site is still up:

  • The sitemap. WordPress publishes one at /wp-sitemap.xml, unless an SEO plugin replaces it with its own.
  • WP-CLI. This prints the address of every published post and page, one per line:
wp post list --post_type=post,page --post_status=publish --field=url > old-urls.txt

Add any custom post types your site uses to --post_type. Category and tag archives aren’t in that list, so take those from the sitemap.

If you migrate with Subset Sync and have Subset Redirects Pro, you can skip this step. Right before the new tables are swapped in, Pro records the URLs of up to 5,000 published posts and term archives on the destination site, and checks each one after the move. See the After migration tab below.

2. Keep the 404 log running

Subset Redirects logs every 404 from the moment it’s active, so install it on the new site before you switch traffic over. Open Subset → Redirects → 404 Log to see each URL a visitor asked for and didn’t find, with its hit count, when it was first and last seen, and the latest referrer. Top open 404s this week shows the busiest ones, which are the redirects to add first.

The same list is available from WP-CLI:

wp subset redirector 404 list --orderby=hits --limit=20

The log adds up to 60 new URLs a minute and stops adding new ones at 10,000 entries. Entries not seen for 30 days are deleted daily. A page cache or CDN that serves a cached 404 never runs WordPress, so those visits aren’t logged. Getting started lists what else the log leaves out.

3. Create the redirects in bulk

Compare your old URL list with the new site. For each old URL that no longer works, add a row to a CSV file with where it should go. Only source is required, and the first row names the columns:

source,target,status_code,query_mode,enabled,group,notes,external,match_type
/old-page,/new-page,301,ignore,1,,,0,exact
/discontinued-widget,,410,ignore,1,,No replacement,0,exact

Use 410 with an empty target for a page that’s gone with nothing to replace it, rather than sending it to the home page. status_code takes 301, 302 or 410, and a row with any other code is rejected. Every column is described in the developer reference.

Go to Subset → Redirects → Import & Export, choose the file under Import redirects and click Upload and preview. You’ll see what each row will add, update, skip or reject before anything is saved. Click Import to save. A row whose source matches an existing redirect updates it. Files can be up to 2 MB and 10,000 rows.

From WP-CLI, preview the file first and then import it:

wp subset redirector redirect import redirects.csv --dry-run
wp subset redirector redirect import redirects.csv

A few more ways to fill gaps:

  • From the 404 log. Click Create redirect on an entry, or select several and use the Redirect to… bulk action to send them all to one target. Saving a redirect marks the matching 404 resolved.
  • From the old site’s redirect plugin. If the old site used Redirection, Yoast SEO Premium or Rank Math, Import from another plugin on the same tab reads its redirects from the database. These imports never change a redirect you already have.
  • For a changed permalink structure. Subset Redirects adds redirects when a single post’s slug changes, but not when the permalink structure changes, because that can change every URL on the site. With Pro, one wildcard or regular expression redirect covers the whole pattern, such as /blog/(\d{4})/(.*) to /articles/$2.

If the domain changed too, the old domain has to reach the new site for any of these redirects to run. Redirects match on the path, so they keep working once it does.

4. Test before you trust them

Browsers cache a 301, so a wrong one can outlast the fix. Import as 302 while you check, then change them to 301 once they’re right. Status codes explains why.

To check one URL, enter its path in the Test a URL box on the Redirects tab and click Test. You’ll see which redirect matches, where it sends the visitor and any further redirects after it. From WP-CLI:

wp subset redirector redirect test /old-page

To check from outside WordPress, request the old URL without following the redirect, so you see the status code as well as the destination:

curl -sS -o /dev/null -w '%{http_code} %{redirect_url}\n' https://example.com/old-page

Over the following weeks, the Hits and Last hit columns on the Redirects tab show which redirects visitors use, with a dash for ones nobody has hit yet. Site Health reports redirect chains and loops under Redirect chains and loops. Keep an eye on the 404 log for URLs your list didn’t include.

With Pro and Subset Sync

With Subset Redirects Pro and a migration run by Subset Sync, the After migration tab replaces steps 1 and 3 for posts and term archives. After the move, it checks every URL Pro recorded on the destination before the swap and sorts them into:

  • Now 404, with a suggested redirect
  • Now 404, with no suggestion
  • Redirects made from this report
  • Still resolve

Tick the suggestions you agree with and click Accept selected. The redirects it makes show Migration as their origin, so you can filter for them later.

Pro also suggests a target for entries in the 404 log, with a confidence score. You can accept one, a selection, or every suggestion above a threshold. Getting started covers the rest of Pro.