Netlify _redirects and netlify.toml cheatsheet for rewrites, proxies, SPA fallbacks, splats, status codes, and country/language rules.
Paste your _redirects file or netlify.toml redirects to parse each rule and catch shadowed rules, bad statuses, and splat mistakes. Search above works without any pasted input.
_redirects file (publish directory root)Plain-text rules file. It must end up in the PUBLISH directory after the build (e.g. `dist/`, `build/`, `public/` output), not just in the repo root.
Watch out: Most "rule not firing" reports are a build that never copies _redirects into the publish directory.
# public/_redirects (Vite / CRA copy public/ verbatim) /old-page /new-page 301
/from [params] /to [status][!] [conditions]One rule per line: origin path, optional query-param matchers, destination, optional status code (default 301), optional force `!`, optional Country/Language/Role conditions.
/old /new
/store id=:id /blog/:id 301
/admin/* /login 302! Role=admin
# comment linesLines starting with `#` are ignored. Use them to group sections — redirect files grow fast on real sites.
# --- marketing pages --- /pricing-old /pricing 301
default status = 301Omitting the status code makes the rule a 301 permanent redirect. Be deliberate: browsers and Google cache 301s aggressively.
Watch out: Use 302 while you are still testing a rule; switch to 301 once it is final.
/old /new # implicit 301
/old /new 302 # explicit temporary
first match wins (top to bottom)Rules are evaluated in file order and evaluation stops at the first match. Put specific rules above broad ones.
Watch out: A `/*` rule anywhere but the last line disables everything below it.
/api/* https://api.example.com/:splat 200 /* /index.html 200
/path https://elsewhere.com/pathDestinations can be absolute URLs on any domain. With 301/302 the browser is sent there; with 200 Netlify proxies the response instead.
/docs https://docs.example.com 301
/api/* https://api.example.com/:splat 200
trailing slashes are normalizedNetlify treats `/about` and `/about/` as the same route for matching, so you do not need duplicate rules for both spellings.
/about /company 301 # also matches /about/
301 — permanent redirectThe URL moved for good. Search engines transfer ranking signals to the target; browsers cache it.
/2019-pricing /pricing 301
302 — temporary redirectThe move is temporary. Nothing is cached long-term and search engines keep indexing the original URL.
/black-friday /deals/2026 302
200 — rewrite (URL unchanged)Serve the destination content while the browser URL stays on the origin path. This is what powers SPA fallbacks and API proxying.
Watch out: 200 rewrites also preserve the request method and body — the only status that does.
/* /index.html 200
/api/* https://api.example.com/:splat 200
404 — custom not-found contentServe specific content with a 404 code. Useful for retired sections that should show an explanation instead of the generic 404 page.
/store/* /store-closed.html 404
410 — goneTells crawlers the content was removed on purpose and will not come back, which de-indexes faster than 404.
/blog/deleted-post /gone.html 410
451 — unavailable for legal reasonsReserved for content blocked by legal requirements, often combined with Country conditions.
/casino/* /unavailable.html 451 Country=de
! — force flag (beat shadowing)By default a rule loses to a real file at the same path. Appending `!` to the status makes the rule win even when the file exists.
Watch out: A forced `/* ... 200!` fallback also swallows your JS and CSS assets — almost never what you want.
/old-file.html /new-file.html 301!
/* → :splatA trailing `*` in the source captures the rest of the path; `:splat` in the target inserts it. The standard way to move whole sections.
/news/* /blog/:splat 301
* must be the last path segmentOnly one splat is allowed and it must sit at the end of the source path. `/a/*/b` is not a valid Netlify pattern.
/downloads/* /files/:splat 301
/:segment placeholdersA `:name` matches exactly one path segment and can be reused (and reordered) in the target.
/news/:year/:month/:slug /blog/:year-:month/:slug 301
:name vs :splatPlaceholders match one segment; the splat matches everything remaining including further slashes. Use placeholders when structure matters.
Watch out: `:splat` in the target is only filled when the source has `*` — otherwise the rule never expands.
/docs/:lang/* /:lang/docs/:splat 301
capture but drop the tailMatch a whole subtree but send everyone to one page: use `*` in the source and simply omit `:splat` in the target.
/legacy/* / 301
/promo-2024/* /promotions 302
/* /index.html 200The single-page-app fallback: every unknown path serves index.html with a 200 so client-side routing handles it, and deep links survive refresh.
/* /index.html 200
SPA fallback must be the LAST ruleFirst match wins, so the catch-all has to sit at the bottom. Anything written after it can never fire.
/api/* /.netlify/functions/api/:splat 200 /* /index.html 200
why the fallback does not break assetsWithout `!`, shadowing lets real files win: `/main.js` exists, so it is served directly and never hits the `/*` rule.
/* /index.html 200 # bundles/images still served normally
keep API routes out of the fallbackProxy or function rules must appear above the SPA fallback, otherwise API calls to unknown paths return index.html with a confusing 200.
Watch out: An API client receiving HTML where it expects JSON is the classic symptom of this ordering bug.
/api/* https://api.example.com/:splat 200 /* /index.html 200
/api/* https://api.example.com/:splat 200Status 200 plus an absolute target = reverse proxy. The browser talks only to your domain; Netlify fetches from the upstream and streams the response back.
/api/* https://api.example.com/v2/:splat 200
proxying kills CORS problemsBecause the request never leaves your origin from the browser's point of view, no CORS headers or preflights are involved at all.
/weather/* https://api.openweathermap.org/:splat 200
pretty URLs for Netlify FunctionsRewrite a clean path onto the functions endpoint so clients never hard-code `/.netlify/functions/`.
/api/* /.netlify/functions/:splat 200
signed proxy redirects (netlify.toml)Set `signed = "MY_SECRET_ENV"` on a proxy rule and Netlify adds a JWT the upstream can verify, proving the request came through your proxy.
[[redirects]] from = "/api/*" to = "https://api.example.com/:splat" status = 200 signed = "API_SIGNATURE_TOKEN"
custom headers on proxied requestsIn netlify.toml a proxy rule can attach headers to the upstream request — handy for API keys that must not ship to the browser.
Watch out: Headers set here go to the origin only; they are not response headers for the visitor.
[[redirects]]
from = "/search/*"
to = "https://api.example.com/:splat"
status = 200
headers = {X-From = "Netlify"}apex ↔ www handled automaticallyNetlify auto-redirects all site aliases to the primary custom domain (including apex vs www), so you rarely write those rules yourself.
# set the primary domain in Site settings → Domain management
https://old.example.com/* → new domainFull-domain migration keeping deep links: absolute URL in the source, `:splat` in the target, force flag on.
Watch out: The old domain must be attached to this Netlify site (domain alias) or the rule never sees its traffic.
https://old.example.com/* https://www.example.com/:splat 301!
route one subdomain into a pathFold a legacy subdomain into a path on the main site while preserving the remainder of each URL.
https://blog.example.com/* https://www.example.com/blog/:splat 301!
http → httpsNetlify serves HTTPS and redirects HTTP automatically once a certificate exists — no manual rule needed.
# automatic — verify the certificate under Domain management → HTTPS
/store id=:id /blog/:id 301Match a query parameter and reuse its value in the target path. The classic pattern for retiring `?id=`-style URLs.
/store id=:id /blog/:id 301
match a fixed parameter valueA literal `key=value` matcher only fires when that exact pair is present in the request.
/search source=newsletter /landing/newsletter 302
all listed params must be presentMultiple matchers AND together: a request missing any of them falls through to the next rule.
Watch out: There is no OR — write one rule per alternative parameter combination.
/report year=:y month=:m /reports/:y/:m 301
query strings are forwarded by defaultA plain redirect carries the original query string along to the destination automatically; you do not restate it.
/old /new 301 # /old?a=1 → /new?a=1
Country=us,caGeo-based routing by ISO 3166 country codes, comma-separated. Great for regional storefronts and legal blocks.
/ /us/ 302 Country=us
/ /anz/ 302 Country=au,nz
Language=en,esRoute by the browser Accept-Language header. Combine with a 302 so users can still navigate to other locales manually.
/ /zh/ 302 Language=zh
/docs/* /es/docs/:splat 302 Language=es
Role=admin (JWT / Identity)Gate paths by roles carried in a Netlify Identity / JWT cookie. Requires the role-based access control feature on paid plans.
/admin/* /admin/:splat 200 Role=admin /admin/* /login 302
nf_country / nf_lang test cookiesSet the `nf_country` or `nf_lang` cookie in your browser to override geo detection while testing conditional rules.
document.cookie = 'nf_country=de' # then reload
always pair conditions with a fallbackConditional rules only cover listed audiences. Add an unconditional rule after them so everyone else has a defined destination.
/ /us/ 302 Country=us / /global/ 302
[[redirects]] blockThe netlify.toml equivalent of one `_redirects` line. Repeat the double-bracket block once per rule; order in the file still matters.
[[redirects]] from = "/old" to = "/new" status = 301
force = trueThe toml spelling of the `!` flag: apply the rule even when a real file exists at the origin path.
[[redirects]] from = "/old.html" to = "/new.html" status = 301 force = true
query = {} and conditions = {}Query matchers and audience conditions become inline tables, with condition values as arrays.
[[redirects]]
from = "/store"
to = "/blog/:id"
status = 301
query = {id = ":id"}
conditions = {Country = ["us", "ca"]}_redirects is processed before netlify.tomlWhen both formats exist, every `_redirects` rule is evaluated first. A matching line there wins over any toml block.
Watch out: Keep all rules in ONE format. Split rule sets are the second most common "why is my rule ignored" cause.
# pick one: public/_redirects OR netlify.toml [[redirects]]
deploy log: "X redirect rules processed"The deploy summary reports how many rules parsed. Invalid lines are skipped silently — if the count is lower than expected, a rule is malformed.
# Deploy summary → "42 redirect rules processed"
rule ignored? check shadowing firstIf a real file exists at the origin path, an unforced rule never fires. Either remove/rename the file or add `!` to the status.
/index.html /welcome 301! # beats the real index.html
rule ignored? check what is above itScan upward for an earlier rule (often a catch-all) that matches the same request. The analyzer on this page flags exactly this.
/* /index.html 200 /old /new 301 # dead: never reached
netlify dev — test rules locallyThe Netlify CLI replays your redirect rules on localhost, so you can verify matching before pushing a deploy.
npm i -g netlify-cli netlify dev curl -sI localhost:8888/old-page | grep -i location
curl -sIL — inspect the live chainFollow the actual redirect chain in production and see every hop, status code, and final target.
curl -sIL https://example.com/old-page | grep -iE "^(HTTP|location)"
stale 301 cached by the browserBrowsers cache 301s hard. When testing changed rules, use a private window or curl — otherwise you are debugging the cache, not Netlify.
curl -sI https://example.com/old-page # bypasses browser cache
SPA + API proxy starterThe most common production file: functions proxy first, external API proxy second, SPA fallback last.
/api/* /.netlify/functions/:splat 200 /upstream/* https://api.example.com/:splat 200 /* /index.html 200
domain migration blockMove a whole legacy domain: forced, permanent, splat-preserving.
https://old.example.com/* https://www.example.com/:splat 301! http://old.example.com/* https://www.example.com/:splat 301!
country routing with fallbackRegional entry points plus a defined default for everyone else.
/ /us/ 302 Country=us / /eu/ 302 Country=de,fr,es,it,nl / /global/ 302
retire a section cleanlyDeleted content: 410 for crawlers, one human-readable explanation page.
/forum/* /forum-closed.html 410 /wiki/* /docs/:splat 301
Searchable Netlify redirects cheatsheet for the rules you actually write: the `_redirects` file format, `netlify.toml` [[redirects]] blocks, 301 vs 302 vs 200 rewrites, the force `!` flag and shadowing, splats and `:splat`, named placeholders, SPA fallbacks (`/* /index.html 200`), API proxying to avoid CORS, query-parameter matching, country / language / role conditions, custom 404 and 410 rules, and the debugging paths for "my rule is not firing". The tool is fully local: search the reference, filter by section, paste a `_redirects` file or a netlify.toml snippet to parse each rule and catch known mistakes — catch-all rules that shadow everything below them, `:splat` without a `*`, placeholders that never match, invalid status codes, and self-redirect loops — then copy the exact rule you need.
Paste or drop your content into the tool panel.
Click the button. All processing is local in your browser.
Copy the result or download to disk in one click.
Use it before upload, handoff, archive, support review, or any moment where a file needs one local check before it leaves your machine.
These links move the current task into a more complete workflow.
Filter to SPA and Proxy, copy the `/api/*` proxy rule and the `/* /index.html 200` fallback, and paste your final file into the analyzer. It confirms the proxy rule sits above the catch-all and warns immediately if the fallback would shadow it.
Search "domain" and copy the `https://old.example.com/* https://www.example.com/:splat 301!` template. The notes explain why the old domain must be added as a domain alias and why the force flag matters on migration rules.
Paste the deployed `_redirects` content into the analyzer. Typical findings: a typo like `:splat` without `*`, a rule swallowed by an earlier catch-all, or an invalid status code that Netlify skipped silently — the deploy log only tells you the count of processed rules.
Putting `/* /index.html 200` above other rules disables every rule below it — first match wins, so the SPA fallback must be the last line.
Writing `:splat` in the target without a `*` in the source produces a rule that never expands; the placeholder is only filled by a splat match.
Forgetting `!` on migration rules means any real file at the old path silently wins over the redirect — shadowing is on by default.
Redirect files often contain internal hostnames and upstream API endpoints, so the paste-in analyzer is deliberately local-only and not synced into URL state. Search terms and category filters are shareable; pasted rules never leave the tab.
Folks in your role tend to reach for these alongside this tool.