How to configure redirects on Vercel

intermediate 12 min read Updated 2026-03-13

Quick Answer

Configure Vercel redirects via vercel.json for build-time pattern matching, dashboard UI for immediate project-level changes, CLI for quick management, or bulk CSV files for thousands of rules. Use 307 temporary or 308 permanent status codes; test in staging and check build logs for errors like invalid formats. Limits include 2048 configuration redirects; use bulk for larger scale.

Prerequisites

Vercel account and deployed project
Vercel CLI installed via npm i -g vercel
vercel.json file in project root (optional)
CSV/JSON file for bulk redirects
API token for CLI automation

Step-by-Step Instructions

Set up configuration redirects in vercel.json

Create or edit vercel.json in your project root with a redirects array containing source, destination, and optional permanent (true for 308). Supports wildcards and geolocation via has conditions. Defaults to 307 temporary and case-insensitive; query params not preserved unless specified. Commit and deploy with vercel deploy or Git push.

{
  "redirects": [
    { "source": "/old-blog", "destination": "/blog", "permanent": true },
    { "source": "/old-about", "destination": "/about", "permanent": false },
    { "source": "/:path*", "destination": "/uk/:path*", "has": [{ "type": "header", "key": "x-vercel-ip-country", "value": "GB" }] }
  ]
}

For Next.js, use <code>next.config.js</code> with <code>async redirects()</code> instead of vercel.json.

Configure bulk redirects with CSV/JSON file

For large-scale redirects, create redirects.csv in your repo with columns source,destination,permanent (true/false). Reference it in vercel.json via "bulkRedirectsPath": "redirects.csv". Deploy to process; check build logs for errors. Supports thousands of simple redirects efficiently.

source,destination,permanent
/old-blog,/blog,true
/old-about,/about,false
/legacy-contact,https://example.com/contact,true

Use JSON/JSONL formats for more complex bulk needs; ideal for migrations exceeding 2048 rules.

Add redirects via Dashboard UI

Access immediate project-level redirects without redeploy: Dashboard > Project > Settings > Redirects tab. Click Create, enter Source (e.g. /old-page), Destination (internal/external), Status (307 default or 308), toggle Case sensitive/Preserve query params. Test staging URL in review, then Publish. Edit/delete via row menu.

Staged redirects allow testing before going live across all deployments.

Manage redirects with Vercel CLI

Run vercel login and vercel link first. List with vercel redirects ls (--staged or --version). Add interactively: vercel redirects add; or direct:

vercel redirects add /old-path /new-path --permanent --status 308 --case-sensitive --preserve-query-params --name "My redirect"

. Changes apply immediately to all deployments.

Use <code>--yes</code> for non-interactive adds in scripts.

Test redirects in preview deployment

Deploy to preview branch or staging to verify behavior before production. Use relative paths in destinations to avoid hardcoding domains. Check vercel logs or dashboard for evaluation order and conflicts between methods (e.g. configuration vs project-level). Ensure geolocation rules work post-deploy, as local vercel dev may not support has.

Handle framework-specific redirects

For Next.js, define in next.config.js:

module.exports = {
  async redirects() {
    return [
      { source: '/old-blog/:slug', destination: '/news/:slug', permanent: true }
    ];
  }
};

Use Vercel Functions or Middleware for dynamic logic without redeploys.

Middleware with Edge Config enables instant updates for critical redirects.

Set domain-level redirects

For apex/www redirects: Project Settings > Domains > Edit domain > Redirect to dropdown. Firewall rules for emergencies execute before other redirects.

Common Issues & Troubleshooting

"Invalid redirect format" or "Failed to process bulk redirects" in build logs

Fix malformed CSV/JSON (exact columns source,destination,permanent with true/false booleans); verify bulkRedirectsPath in vercel.json. Check logs with vercel logs.

Redirects not triggering or conflicting

Verify evaluation order (Firewall > configuration > project-level); test staging URLs and use vercel redirects ls. Avoid overlaps between vercel.json, dashboard, and CLI.

Geolocation rules not working locally

Deploy to test has conditions like x-vercel-ip-country; vercel dev does not support them yet.

Exceeding 2048 redirect limit

Switch to bulk redirects via CSV/JSONL for large-scale lists; configuration redirects capped at 2048.

Query params or case sensitivity issues

Enable --preserve-query-params or dashboard toggle; set --case-sensitive explicitly. Defaults preserve neither.

Visit Vercel View Vercel Pricing