Intermediate
How to configure redirects on Vercel
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
1
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" }] }
]
}Tip
For Next.js, use
next.config.js with async redirects() instead of vercel.json.2
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,trueTip
Use JSON/JSONL formats for more complex bulk needs; ideal for migrations exceeding 2048 rules.
3
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.Tip
Staged redirects allow testing before going live across all deployments.
4
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.Tip
Use
--yes for non-interactive adds in scripts.5
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.6
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 }
];
}
};Tip
Middleware with Edge Config enables instant updates for critical redirects.
7
Set domain-level redirects
For apex/www redirects: Project Settings > Domains > Edit domain > Redirect to dropdown. Firewall rules for emergencies execute before other redirects.
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.
Ready to get started with Vercel?
Put this tutorial into practice. Visit Vercel and follow the steps above.
Visit Vercel →