Redirects
A distribution's redirects are part of its settings: an ordered list of rules under redirects. Visitors get the redirect table of the live deployment. A change goes live when the deployment it created is promoted, and a rollback brings back the earlier table.
To manage more than a few rules, see Migrate redirects from another host.
Rule format
{
"redirects": [
{ "from": "/pricing-2025", "to": "/pricing" },
{ "from": "/blog/*", "to": "/news/:splat", "status": 301 },
{ "from": "/docs/*", "to": "https://docs.acme.example/:splat", "status": 302, "query": "drop" }
],
"redirect_hosts": ["docs.acme.example"]
}| Field | Required | Value |
|---|---|---|
from | yes | A path starting with /. No query string or #fragment. May end in * to match everything below a prefix. |
to | yes | A path starting with /, or an https:// URL. :splat is replaced by what * matched. |
status | no | 301 (default), 302, 307 or 308 |
query | no | preserve (default) or drop |
redirect_hosts lists other hosts that to may point at (see Off-site targets).
How a request is matched
- Exact rules first. The request path is compared with every
fromthat has no*. One trailing slash is ignored, so/about/matchesfrom: "/about". - Then patterns, in the order you wrote them. The first
fromending in*whose prefix matches wins./blog/*matches/blog/2026/launch(:splatis2026/launch) and also/blogitself (:splatis empty). - No match: the request is served normally.
Paths are compared percent-encoded, with escapes in upper case. /café, /caf%c3%a9 and /caf%C3%A9 are the same rule, and Edge stores it as /caf%C3%A9. Matching is case-sensitive otherwise.
The order of checks on every request is:
- A suspended distribution answers
403. - A taken-down distribution answers
410or its redirect. - Redirect rules.
- Password protection, then the site's files.
So a redirect works even on a password-protected distribution, and the visitor signs in on the page they are redirected to.
Status codes
| Status | Meaning | Browser caching |
|---|---|---|
301 | Moved permanently | Cached with no expiry |
308 | Moved permanently, method and body kept | Cached with no expiry |
302 | Found (temporary) | Not cached (Cache-Control: no-store) |
307 | Temporary, method and body kept | Not cached (Cache-Control: no-store) |
A visitor who received a 301 or 308 keeps going straight to the old target, even after you change or remove the rule. Use 302 while you are still checking a migration, and switch to 301 once it is right.
Query strings
With query: "preserve" (the default), the visitor's query string is added to to. If to already has one, the two are joined with &:
| Rule | Request | Location |
|---|---|---|
/old → /new | /old?utm_source=mail | /new?utm_source=mail |
/campaign → /landing?ref=edge | /campaign?gclid=x1 | /landing?ref=edge&gclid=x1 |
/clean → /fresh, query: "drop" | /clean?a=1 | /fresh |
from never matches on query strings.
Off-site targets
A to that is an https:// URL must point at one of:
- the distribution's own address,
{slug}.edge.deca-dev.com; - a custom domain attached to the distribution, or verified in the workspace;
- a host listed in the distribution's
redirect_hosts(up to 20).
Anything else is rejected. This stops a redirect on your verified domain from sending visitors to a site you do not control. Plain http:// targets are rejected. :splat may appear in the path, query, or fragment. It cannot appear in the host, including the user name.
Checks Edge runs before saving
A redirect table is checked when you update the distribution, import, or check a deployment. A table that fails is not saved, and every problem is listed:
| Check | Result |
|---|---|
| A rule that leads back to itself, directly or through other rules | Rejected: redirect loop: /a -> /b -> /a |
| A chain that does not end within 10 redirects | Rejected |
Two rules with the same from (after normalising) | Rejected |
| An off-site host that is not allowed | Rejected |
| A rule that takes more than one redirect to settle | Warning only: /a takes 2 redirects to settle |
Limits on the number and length of rules are on Limits.
Import formats
edge_redirect_import (POST /v1/distributions/{id}/redirects/import, edge redirects import) reads three formats. Errors are reported per line.
CSV. The first row is a header naming from and to, with optional status and query columns. Blank lines and lines starting with # are skipped.
from,to,status,query
/pricing-2025,/pricing,,
/blog/*,/news/:splat,301,
/docs/*,https://docs.acme.example/:splat,302,dropNetlify _redirects. One rule per line: from to [status]. A trailing ! on the status is accepted and ignored, because Edge rules always apply before the site's files.
/pricing-2025 /pricing
/blog/* /news/:splat 301These Netlify features are not supported and are reported as errors on their line: status 200 rewrites, 404 custom pages, placeholders other than * and :splat (such as /news/:year), and query, country, language or role conditions.
JSON. An array of rules, or {"redirects": [...]}. This is the format edge_redirect_export writes with format: "json".
mode: "merge" (the default) updates rules whose from already exists, in place, and adds new ones at the end. mode: "replace" keeps only the imported rules. If the same from appears twice in one import, the later line wins.