Fixing the Redirect Map for a Site Migration

What a good redirect map looks like

A redirect map is a table. Each row holds one address from the old site and the one address on the new site that replaces it. Everything else in the migration depends on it: the redirect rules are generated from it, the post-launch checks are run against it, and when rankings wobble it is the first document you open to find out why.

A usable map has more than two columns. The extra columns are what let you prioritise, review and test it without guesswork.

The two failures the Site Migration Audit most often exposes are rows that were never in the map at all, and rows whose destination is itself redirected, missing or unrelated. Both are problems with the map, not with the server, which is why fixing the spreadsheet comes before touching any configuration.

Where the old URLs come from

No single source lists every address a site has ever used. A crawl only finds pages that are linked; a sitemap only lists what the old CMS chose to include; analytics only shows pages that were visited. Combine several, and keep a note of where each URL came from.

• A full crawl of the old site. Run it before launch if you still can. Include images and PDFs if they attract links or traffic.
• Old XML sitemaps. Save copies of every sitemap file, including ones for images, video and news.
• Search Console performance report. Export pages with clicks or impressions over the last 16 months, which is the longest range it holds.
• Search Console links report. The top linked pages list shows old URLs that other sites point to, including ones no longer linked internally.
• Analytics landing pages. Pull a year or more of landing-page data to catch seasonal pages that a crawl in June will not see in use.
• Server access logs. Requests that returned 200 over recent months reveal orphan pages, old campaign URLs and files that nothing links to any more.
• Existing redirect rules. Export the current .htaccess, nginx config, plugin list or platform redirect table. Their source addresses are old URLs too.

Choosing the right destination for each row

Matching is where judgement matters. A redirect passes an old page's signals to the new address only when the new page genuinely replaces it. Google has said that redirecting many unrelated pages to one destination, such as the home page, can be treated like a soft 404, so the value of those old URLs is largely lost.

The four kinds of row

1. Exact equivalents. The same product, article or service at a new address. These should be the large majority.
2. Pattern matches. Whole sections that moved with a predictable change, such as /blog/YYYY/MM/slug/ becoming /articles/slug/. One rule can cover thousands of rows, but check a sample by hand.
3. Merges. Several thin old pages combined into one new page. Redirect each to the merged page only if the merged page covers what each old page covered.
4. Retirements. Content with no successor. A 410 or a helpful 404 is more honest than a redirect to a loosely related page. If a close parent category genuinely serves the same need, that is acceptable.

Matching at scale

For large sites, match by something more stable than the path. Product SKUs, article IDs, ISBNs or the page title are good join keys. Export the old site with its IDs, export the new site with the same IDs, and join the two in a spreadsheet with XLOOKUP or VLOOKUP. Only the rows that fail to join need human attention.

=XLOOKUP(C2, NewSite!C:C, NewSite!A:A, "NO MATCH")

Rows that come back as NO MATCH are exactly the ones worth a person's time. Sort them by clicks and linking domains so the valuable ones are decided first.

Legacy redirects and the hidden second hop

Most sites have been rebuilt before. The old configuration may already contain redirects from an earlier redesign, such as /products.php?id=88 to /shop/oak-desk-120cm.html. If you add a new rule from /shop/oak-desk-120cm.html to the new address and leave the old rule alone, the oldest links now travel through two redirects.

The fix belongs in the map. Add every legacy source to the map as its own row, and set its destination to the final new URL. Then no rule points at an address that is itself redirected. The redirect checker guides on this site cover diagnosing chains in general; here the aim is simply that the map never creates them.

A quick way to find rows that would create a chain is to look up every destination in the old-URL column. Any destination that also appears as a source is a second hop.

=IF(COUNTIF(A:A, B2) > 0, "CHAIN: destination is also redirected", "")

Turning the map into redirect rules

How you implement the map depends on the platform, but the principle is the same: keep exact rows in a lookup table and keep only a small number of pattern rules. Hundreds of separate regular expressions are slow to evaluate and hard to review.

nginx: a map file

nginx's map directive reads a two-column list and performs one lookup per request, which suits large redirect maps well. Export the spreadsheet as two columns and include it.

# /etc/nginx/redirects.map  (generated from the spreadsheet)
/shop/oak-desk-120cm.html      /furniture/desks/oak-desk-120/;
/products.php?id=88            /furniture/desks/oak-desk-120/;
/about-us.html                 /about/;

# in the http block
map $request_uri $migrate_to {
    default "";
    include /etc/nginx/redirects.map;
}

# in the server block
if ($migrate_to) {
    return 301 https://www.example.co.uk$migrate_to;
}

Because $request_uri includes the query string, a row with parameters only matches that exact string. Decide how to handle unexpected parameters on otherwise mapped paths, such as tracking tags, before launch.

Apache

For short maps, Redirect 301 lines work. For long ones, a RewriteMap in the server configuration (it cannot be declared in .htaccess) gives the same single-lookup behaviour as nginx.

CMS and hosted platforms

WordPress redirect plugins, Shopify's URL redirects and most headless hosts accept a CSV import. Check the import's limits and whether it matches query strings and trailing slashes, and import a small test file first. Remember that some platforms only apply their redirect table when no live page exists at the old path.

Which status code

Use 301 or 308 for moved pages. Google treats both permanent and temporary redirects as signals for choosing which URL to index, but a permanent code states the intent plainly and is what its site-move guidance recommends. The practical risk with a stray 302 is small; the bigger risks are missing rows and wrong destinations.

The fix, step by step

A test script you can run against the map

Testing a few addresses by hand is not enough; the only reliable test is every row. This short Python script reads the map as a CSV with old, new and status columns and reports each row that does not behave as expected. It uses the widely used requests library.

import csv, sys, requests

HOST = sys.argv[1]            # e.g. https://staging.example.co.uk
fails = 0
with open("redirect-map.csv", newline="") as f:
    for row in csv.DictReader(f):
        r = requests.get(HOST + row["old"], allow_redirects=False, timeout=15)
        want = int(row["status"])
        got_to = r.headers.get("Location", "")
        if r.status_code != want:
            print("STATUS", row["old"], r.status_code, "expected", want); fails += 1
            continue
        if want in (301, 308) and not got_to.endswith(row["new"]):
            print("TARGET", row["old"], got_to, "expected", row["new"]); fails += 1
            continue
        if want in (301, 308):
            d = requests.get(HOST + row["new"], allow_redirects=False, timeout=15)
            if d.status_code != 200:
                print("DEST", row["new"], d.status_code); fails += 1
print("failures:", fails)

Three kinds of failure come out of it. STATUS means the old path returned the wrong code, often a 200 because a page still exists at that path, or a 404 because the row was never loaded. TARGET means the redirect went somewhere other than the mapped page. DEST means the destination itself is missing or redirects again. Each points to a different fix, so keep them separate in your notes.

Keeping the map healthy after launch

• Keep the spreadsheet as the source of truth. Every new redirect goes into the map first, then into the rules. Editing server files directly is how maps and rules drift apart.
• Update rows when pages move again. If a new page is later renamed, change the destination on every row pointing at it rather than adding another hop.
• Keep redirects for the long term. Google advises keeping site-move redirects for at least a year; old links on other sites last far longer, so most sites keep them indefinitely.
• Watch for new 404s from old paths. A monthly check of logs and the Search Console Not found list will surface old URLs that no source captured, such as addresses printed in brochures or used in email campaigns.
• Update internal links. Redirects are a safety net for outside links. Your own navigation, content and sitemaps should point straight at the new addresses.

For broader checks on status codes, chains and platform-specific rule syntax, the Redirect Checker Guide goes into more depth. For choosing what to do with URLs that have no obvious replacement, see Fixing Lost URLs After a Migration.