Skip to content

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 ​

json
{
  "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"]
}
FieldRequiredValue
fromyesA path starting with /. No query string or #fragment. May end in * to match everything below a prefix.
toyesA path starting with /, or an https:// URL. :splat is replaced by what * matched.
statusno301 (default), 302, 307 or 308
querynopreserve (default) or drop

redirect_hosts lists other hosts that to may point at (see Off-site targets).

How a request is matched ​

  1. Exact rules first. The request path is compared with every from that has no *. One trailing slash is ignored, so /about/ matches from: "/about".
  2. Then patterns, in the order you wrote them. The first from ending in * whose prefix matches wins. /blog/* matches /blog/2026/launch (:splat is 2026/launch) and also /blog itself (:splat is empty).
  3. 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:

  1. A suspended distribution answers 403.
  2. A taken-down distribution answers 410 or its redirect.
  3. Redirect rules.
  4. 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 ​

StatusMeaningBrowser caching
301Moved permanentlyCached with no expiry
308Moved permanently, method and body keptCached with no expiry
302Found (temporary)Not cached (Cache-Control: no-store)
307Temporary, method and body keptNot 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 &:

RuleRequestLocation
/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:

CheckResult
A rule that leads back to itself, directly or through other rulesRejected: redirect loop: /a -> /b -> /a
A chain that does not end within 10 redirectsRejected
Two rules with the same from (after normalising)Rejected
An off-site host that is not allowedRejected
A rule that takes more than one redirect to settleWarning 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.

csv
from,to,status,query
/pricing-2025,/pricing,,
/blog/*,/news/:splat,301,
/docs/*,https://docs.acme.example/:splat,302,drop

Netlify _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.

text
/pricing-2025  /pricing
/blog/*        /news/:splat   301

These 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.

See also ​