---
title: Six enterprise redirect antipatterns
description: Avoid broken migration URLs and unnecessary application work. Choose the right redirect method and test changes before cutover.
url: "https://vercel.com/kb/guide/six-enterprise-redirect-antipatterns"
published: 2026-11-18
last_updated: 2026-11-18
authors: Forward Deployed Engineering Team, Dom Sipowicz
install_vercel_plugin: npx plugins add vercel/vercel-plugin
search_with_vercel_cli: npx vercel@latest kb search "<query>"
read_with_vercel_cli: "npx vercel@latest kb inspect six-enterprise-redirect-antipatterns"
---

Enterprise migrations can leave redirect rules behind in a legacy CDN even when the public URLs stay the same. If those rules stop working at cutover, old links can return errors or send visitors to the wrong destination.

Known redirect mappings can resolve at Vercel's CDN before application code runs. Keep CMS and database reads off that path and reserve per-request logic for decisions the platform's routing rules cannot express.

Vercel's Forward Deployed Engineers see these six antipatterns in enterprise migrations. They range from missing URL mappings to redirect lookups that add application work to otherwise cacheable requests.

## Why redirects matter on a migration

Consolidating a frontend on Vercel means accounting for rules in every existing CDN and application. Export those rules before removing a provider from the request path, including redirects on old domains that will remain in use.

FDE engagements have involved 3,000 to more than 250,000 redirects, including roughly 15,000 across 185 sites in one program. Shared inventories help teams find duplicates, chains, and conflicting destinations.

For URLs that move, permanent redirects help search engines associate the old page with its replacement and consolidate signals. Rankings can fluctuate during a [URL migration](https://developers.google.com/search/docs/crawling-indexing/site-move-with-url-changes). URLs with no relevant replacement should return `404` or `410` rather than redirect visitors to an unrelated page.

Use `308` for permanent redirects and `307` for temporary ones to preserve the request method and body. Google treats `301` and `308` as permanent redirect signals; choosing `308` adds no SEO benefit.

## The six antipatterns

### Missing redirects at cutover

The new site passes QA, but testing covers only its new URLs. Redirects for changed paths or retired domains are missing from the migration plan, leaving old bookmarks, backlinks, and search results pointing to errors.

Map each moved URL to its relevant replacement before cutover. Include the old hosts as well as paths, and avoid redirect chains by pointing directly to the final destination.

Export the legacy URL inventory and load known mappings into [Bulk Redirects](https://vercel.com/docs/routing/redirects/bulk-redirects). Stage and test the rules against important inbound URLs before publishing them. For a site move, keep redirects in place for at least a year so Google has time to process the change.

### Querying a CMS on every request

Content editors maintain redirects in a CMS, and Proxy queries that CMS for every matching request. Keeping the CMS as the source of truth is reasonable; making each request wait for it adds a dependency to serving the site.

```typescript
import { NextResponse, type NextRequest } from "next/server";

export async function proxy(request: NextRequest) {
  // Antipattern: a network call to the CMS on every request
  const res = await fetch(
    `https://cms.example.com/api/redirects?path=${request.nextUrl.pathname}`,
  );
  const entry = await res.json();

  if (entry) {
    return NextResponse.redirect(new URL(entry.destination, request.url), 308);
  }

  return NextResponse.next();
}
```

Requests wait for the CMS round trip even when no redirect exists. In one FDE engagement, CPU throttling rose from roughly 1.5% to 7% after a team replaced a database-backed redirects API with Global Config and Proxy. Changing the store still left redirect work in the application request path.

Redirects generated from `next.config` change with a deployment. ISR and content revalidation do not regenerate that configuration.

Export the CMS mappings to a Bulk Redirects file during the build, or publish them through the redirect API or CLI without redeploying. Both approaches keep CMS reads out of incoming requests. The [CMS integration](https://vercel.com/kb/guide/managing-redirects-from-your-cms-using-vercel-bulk-redirects) shows how to generate the file from `vercel.ts`.

The generator below assumes a CMS adapter that returns every mapping as `{ from, to }`. It treats the exported redirects as permanent; preserve individual status codes if your source contains temporary redirects.

```typescript
// Build-script excerpt. Implement fetchRedirectsFromCMS
// in your CMS adapter.
import { mkdir, writeFile } from "node:fs/promises";
import { fetchRedirectsFromCMS } from "../lib/cms-redirects";

// The adapter returns every redirect as { from: string, to: string }.
// This example assumes every exported redirect is permanent.
const entries = await fetchRedirectsFromCMS();
const rows = entries.map((entry) =>
  JSON.stringify({
    source: entry.from,
    destination: entry.to,
    permanent: true,
  }),
);

await mkdir("redirects", { recursive: true });
await writeFile("redirects/redirects.jsonl", rows.join("\n"), "utf8");
```

### Looking up redirects after a page miss

The application fetches a page first and checks a redirect store only if that page is missing. Legacy URLs then wait for both operations before receiving a redirect. In this excerpt, `getPage`, `lookupRedirect`, and `PageContent` stand for application-specific code.

```tsx
import { notFound, redirect } from "next/navigation";

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string[] }>;
}) {
  const { slug } = await params;
  const page = await getPage(slug);

  if (!page) {
    // Antipattern: a second round trip after the render already missed
    const entry = await lookupRedirect(`/${slug.join("/")}`);
    if (entry) redirect(entry.destination);
    notFound();
  }

  return <PageContent page={page} />;
}
```

The two lookups run in sequence even though `PageContent` never renders for the redirected request. Resolve known mappings before fetching page data. Bulk Redirects handles exact matches at the CDN without invoking Proxy or the page.

For an application-managed map, the Proxy below uses `bloom-filters` and a generated filter to rule out paths before the full lookup. Its `/api/redirects` handler must confirm possible matches by returning an entry or `null`, because the filter can return false positives.

This Next.js 16+ excerpt assumes an app at the domain root. Adapt the filter keys, lookup path, and destinations together for `basePath` or locale prefixes.

```typescript
import { NextResponse, type NextRequest } from "next/server";
import { ScalableBloomFilter } from "bloom-filters";
import GeneratedBloomFilter from "./redirects/bloom-filter.json";

type RedirectEntry = {
  destination: string;
  permanent: boolean;
};

const bloomFilter = ScalableBloomFilter.fromJSON(GeneratedBloomFilter as any);

export async function proxy(request: NextRequest) {
  const pathname = request.nextUrl.pathname;
  if (!bloomFilter.has(pathname)) return NextResponse.next();

  const api = new URL("/api/redirects", request.url);
  api.searchParams.set("pathname", pathname);

  try {
    const response = await fetch(api);
    if (!response.ok) return NextResponse.next();

    const entry: RedirectEntry | null = await response.json();
    if (entry) {
      return NextResponse.redirect(
        new URL(entry.destination, request.url),
        entry.permanent ? 308 : 307,
      );
    }
  } catch (error) {
    console.error("Redirect lookup failed", error);
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
};
```

Regenerate and redeploy the imported filter when adding source paths. The matcher excludes the lookup handler to prevent recursive requests, along with other API routes and framework assets.

The example continues to normal routing if the lookup fails. Choose a different failure policy if a redirect is required for the request to be handled correctly.

### Repeating a rule for every URL

Renaming `/shoes/` to `/footwear/` can create thousands of exact mappings that preserve the same product slug. One configuration rule can replace them when they follow the same transformation; keep exact entries for exceptions.

Use [configuration redirects](https://nextjs.org/docs/app/api-reference/config/next-config-js/redirects) or [project routing rules](https://vercel.com/docs/routing/project-routing-rules) for path patterns and request conditions. Bulk Redirects supports exact paths and fully qualified source URLs, so an exact host-and-path match can also stay in the bulk map.

The pattern matches one product-slug segment. Compare it with the exact mappings in the second tab. Use a catch-all only if nested paths follow the same transformation. Both versions preserve query parameters.

**Pattern rule**

```typescript
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  async redirects() {
    return [
      {
        source: "/shoes/:slug",
        destination: "/footwear/:slug",
        permanent: true,
      },
    ];
  },
};

export default nextConfig;
```

**Exact entries**

```json
[
  {
    "source": "/shoes/air-max-90",
    "destination": "/footwear/air-max-90",
    "permanent": true,
    "preserveQueryParams": true
  },
  {
    "source": "/shoes/gel-kayano-31",
    "destination": "/footwear/gel-kayano-31",
    "permanent": true,
    "preserveQueryParams": true
  }
]
```

For locale-prefixed paths, use exact entries when destinations differ by locale. Use a pattern when every locale follows the same mapping, and test locale casing and exceptions before publishing it.

### Overloading configuration redirects

Putting every exact mapping into `next.config` or `vercel.json` increases the deployment route table and makes a large migration map harder to maintain alongside application routing.

In one FDE engagement, adding roughly 900 redirects from a 5,000-line JSON file coincided with a rise in CPU use and function duration. Configuration redirects run in Vercel's routing layer, so investigate request traces before attributing an application CPU spike to those rules.

Vercel currently lists a [deployment route limit](https://vercel.com/docs/limits) of 2,048 on Hobby and Pro, with custom limits on Enterprise. That limit covers routes, not a separate allowance reserved for redirects. Ordered configuration rules can also require more matching work as the list grows.

Keep pattern rules and conditions in configuration, and move large exact-match sets to Bulk Redirects. Its [Bloom filter and indexed lookup](https://vercel.com/blog/scaling-redirects-to-infinity-on-vercel) avoid scanning an ordered regex list for each request.

Pro includes 1,000 Bulk Redirects per project. Enterprise capacity is custom, and Pro can add capacity in packs of 25,000 up to 1,000,000 redirects. Check the [current allowance](https://vercel.com/docs/routing/redirects/bulk-redirects) for the target project.

### Using a key-value store for a static redirect map

Proxy can read a redirect map from Global Config or another key-value store. Without a prefilter, each matching request performs a lookup. With the Bloom filter shown above, only possible matches read the full map, although Proxy still runs for requests covered by its matcher.

Global Config is designed for fast reads from replicated data. Its limits are different from a dedicated redirect service: each store supports up to 1 MB, and writes can take up to 10 seconds to propagate. Check the serialized map size rather than assuming a particular number of entries will fit.

Use Bulk Redirects for known exact mappings, including mappings that editors update without a deployment. Keep Proxy for decisions that need application logic or request data beyond the routing rules available to you. Cache shared results only when doing so preserves those decisions; user-specific redirects must not be reused across users.

## The recommended architecture

For path-based WAF redirects and the routing methods below, the order is WAF, Bulk Redirects, project routing rules, deployment configuration, and then Proxy. Matching redirects return a response before later routing layers run.

Choose the earliest layer that can express the rule. Updating a mapping without a deployment does not require running application code to look it up:

| Method                  | Matches                                           | Application work                           | Update path                               |
| ----------------------- | ------------------------------------------------- | ------------------------------------------ | ----------------------------------------- |
| WAF                     | Original-request conditions, such as path or host | No function invocation                     | Publish a rule                            |
| Bulk Redirects          | Exact paths or host-and-path pairs                | No function invocation                     | Deploy a file or publish a staged version |
| Project routing rules   | Patterns and conditions                           | No function invocation                     | Publish a rule                            |
| Configuration redirects | Patterns and conditions                           | No function invocation                     | Deploy configuration                      |
| Proxy                   | Application logic                                 | Proxy runs; store reads depend on the code | Deploy code or update its data source     |

Use [WAF redirect rules](https://vercel.com/docs/vercel-firewall/vercel-waf/rule-configuration) when an immediate operational response needs to take precedence over routing. The default is `307`; the CLI's `--redirect-permanent` option selects `301`.

Rules using resolved **Route** or **Server Action** conditions run later, after middleware. The ordering above applies to original-request conditions, such as path and host.

### Generate redirects before deployment

Run the CMS generator from the project root as part of the build, before the build finishes. It writes `redirects/redirects.jsonl`. CMS changes take effect on the next deployment; a CMS webhook can trigger that deployment.

Install `@vercel/config` and point the project-root `vercel.ts` at that exact file:

```typescript
import type { VercelConfig } from "@vercel/config/v1";

export const config: VercelConfig = {
  bulkRedirectsPath: "redirects/redirects.jsonl",
};
```

Bulk Redirects supports `301`, `302`, `303`, `307`, and `308` through `statusCode`. Setting `permanent: true` selects `308`; an explicit `statusCode` takes precedence.

Both `caseSensitive` and `preserveQueryParams` default to `false`, so matching ignores path case and incoming query parameters are dropped. Query parameters do not select a Bulk Redirects destination, even when forwarding is enabled.

The JSONL and JSON tabs show equivalent entries. Setting `caseSensitive: true` keeps case-only paths distinct. Incoming query parameters are dropped because `preserveQueryParams` is omitted:

**JSONL**

```json
{"source":"/old","destination":"/new","permanent":true,"caseSensitive":true}
```

**JSON**

```json
[
  {
    "source": "/old",
    "destination": "/new",
    "permanent": true,
    "caseSensitive": true
  }
]
```

If you maintain JSON instead, save it as `redirects/redirects.json` and set `bulkRedirectsPath` to that path.

### Update redirects without deploying

From the linked project directory, import your CSV export and inspect the staged version. Published redirects apply across all project deployments and environments:

```bash
vercel redirects import redirects.csv
vercel redirects list --staging
vercel redirects list-versions
```

Test representative paths using the staging URLs in the dashboard review dialog; listing rules does not test responses. Once those checks pass, replace `your_staged_version_id` with the staged version from the list and publish it:

```bash
vercel redirects promote your_staged_version_id
```

To roll back, find the earlier version with `vercel redirects list-versions`. Replace `your_previous_version_id` in `vercel redirects restore your_previous_version_id`; restoring changes the live redirect set immediately.

Imports add to the existing project-level set by default. Use `--force` only when the import contains the entire replacement set, including any rules you still need. It replaces that set rather than adding the export to it.

Keep the deployment file and project-level redirect set under explicit ownership so one does not silently override the other. See the [redirect management workflow](https://vercel.com/docs/routing/redirects/manage-redirects-at-scale) for staging and version management.

### Operational practices

#### Keep the redirect inventory complete

Include rules from old CDNs, applications, and domains. Validate export counts, include all CMS pages, and retain temporary status codes where they are intentional. Trigger a deployment or publish a project-level version when the source changes.

#### Test staged rules before promotion

Use the dashboard staging URLs to check important inbound paths, locale variants, query strings, and destinations. Testing a staged redirect version does not require deploying the application to a lower environment.

#### Check loops, chains, and destinations

Walk the redirect map for cycles and broken destinations before publishing. Test case-only changes such as `/ja-jp` to `/ja-JP`, which can loop when a rule matches its own destination.

[Project routing rules](https://vercel.com/docs/routing/project-routing-rules) inherit case sensitivity from deployment configuration. Enable **Case Sensitive** on a case-normalization rule to prevent a match against the corrected path.

Repeat these checks on a schedule to catch destinations that change after release. Point old URLs directly at their final replacements wherever possible.

#### Monitor redirected requests

Use [CDN Requests in Observability](https://vercel.com/docs/observability/insights#cdn-requests) to inspect redirect traffic. Filtering or breaking down requests by redirect location requires Observability Plus.

On Pro or Enterprise, configure [Log Drains](https://vercel.com/docs/drains/reference/logs) with the `redirect` source to export these requests. Compare status codes and request paths, including query strings, with the intended mapping. Parameters such as `?id=` are not inherently duplicates; investigate variants that serve the same content or create unnecessary crawlable URLs.

## FAQ

### How do I add a redirect on Vercel?

Use `next.config` or `vercel.json` for redirects that ship with application code. For changes without a deployment, use project routing rules or Bulk Redirects. WAF redirect rules can take precedence when you need an operational override.

### How should I manage a large redirect set?

Store known exact mappings in Bulk Redirects and use configuration or project routing rules for shared patterns. Keep one inventory with an owner, test the staged changes, and reserve Proxy for decisions that need application logic.

### How do redirect methods compare on cost?

Configuration redirects do not invoke your functions, and WAF custom rules have no additional rule charge. Bulk Redirects includes a project allowance, with paid additional capacity on eligible plans.

Proxy adds application execution, and storage or CMS lookups can add their own usage charges. CDN request and transfer charges can still apply when a redirect is handled by the platform. Compare the [current pricing](https://vercel.com/docs/pricing) for the methods and traffic your project uses.

### Why are redirects important for SEO?

Permanent redirects tell search engines that a page has moved and help consolidate signals at its replacement URL. Map old pages to relevant destinations, avoid chains where possible, and keep migration redirects for at least a year. Rankings can fluctuate while search engines process the move.

### Can I update redirects without redeploying?

Yes. Publish a new Bulk Redirects version or update project routing rules without deploying the application. The platform can still resolve those redirects before application code runs.

Use Proxy when the destination must be computed from application-specific inputs on each request. Changing a stored destination frequently does not, by itself, require Proxy.

### Can Bulk Redirects handle every redirect?

Bulk Redirects handles exact paths and fully qualified source URLs. It does not support wildcards, regex patterns, or header-based matching, and it ignores query parameters when matching the source.

Use configuration or project routing rules when a query parameter selects the destination, or for other supported patterns and conditions. Reserve Proxy for application logic those rules cannot express.

## Audit an existing project

Use this prompt to audit your repository and available Vercel project settings:

### Agent prompt

```txt
Audit this repository and its Vercel project for redirect problems. Report findings before making changes.

Check for missing migration mappings; CMS or database reads on incoming requests; redirect lookups after page-data misses; repeated exact mappings that could share a pattern; oversized configuration route tables; and static maps served through application code.

Inspect WAF rules, Bulk Redirects, project routing rules, deployment configuration, and Proxy. If a source is unavailable, mark it uninspected rather than assuming it has no rules.

For each finding, cite the file and line or project setting, explain its effect, and propose the smallest appropriate fix. Preserve status codes, host and locale scope, case matching, query handling, and intentional exceptions.

Check for duplicate sources, redirect loops, chains, missing destinations, stale Bloom filters, and overlapping rule ownership. Distinguish publishing a stored mapping without deployment from computing a destination on each request.

Finish with a proposed migration and rollback plan. Identify mappings suitable for Bulk Redirects, patterns suitable for configuration or project routing, and cases that still need Proxy. Do not change or promote production rules during the audit.
```

## Next steps

- [Generate redirect files from your CMS](https://vercel.com/kb/guide/managing-redirects-from-your-cms-using-vercel-bulk-redirects) while keeping editors' existing workflow.
  
- Publish or restore redirect mappings [without redeploying](https://vercel.com/docs/cli/redirects) your application.
  
- [Configure an emergency redirect](https://vercel.com/kb/guide/emergency-redirect) when a WAF rule needs to take precedence.
  
- Use a [Bloom filter](https://nextjs.org/docs/app/guides/redirecting#managing-redirects-at-scale-advanced) if your redirect map still needs application code.

## Reference Architecture

Choose a stack and work through the decisions behind it, with curated documentation, guides, templates, and courses to help you build.

- [Agent stack](/kb/architecture/agents): Build and operate agents with models, tools, and durable workflows.
- [Web applications](/kb/architecture/web): Choose rendering, data, authentication, and caching approaches.
- [Backends](/kb/architecture/backends): Choose a runtime, connect services, and run background work.

[Browse all stacks](/kb/architecture)

## Build with prompts

Build an app, extend an agent, or improve your project with ready-to-use prompts for your coding agent.

[Browse the prompt library](/kb/prompts) · [Read the Markdown index](/kb/prompts.md)

## Search guides from your terminal

Search the Knowledge Base and read guides as Markdown with the Vercel CLI. No login required.

```bash
# Find guides by keyword
npx vercel@latest kb search "rewrites and redirects"
npx vercel@latest kb search "AI SDK streaming"

# Show the latest guides
npx vercel@latest kb

# Print a guide as Markdown, by slug or URL
npx vercel@latest kb inspect <guide>
```
