Which Netlify redirect wins when file and configuration rules overlap?

Definition: Netlify combines redirect rules from the deployed _redirects file and the netlify.toml configuration file, then reads the combined sequence from top to bottom. The first matching rule wins, with _redirects rules processed before netlify.toml rules.

Key facts

• Netlify supports a plain _redirects file in the publish directory and redirects tables in netlify.toml, according to its redirects and rewrites documentation.
• The same documentation states that rules in _redirects are always processed before rules in the Netlify configuration file.
• Within the resulting sequence, the redirects engine processes the first matching rule from top to bottom.
• Netlify's redirect options documentation recommends placing a specific path before a broader splat rule because the broader match can consume the request first.
• A redirect can still be shadowed by content at the source path. Netlify documents ! in _redirects and force = true in netlify.toml for this case.

Which source wins when both rules match?

The _redirects file has precedence over the Netlify configuration file. Netlify's documentation describes the two supported locations, then gives the processing rule: the engine reads rules from top to bottom, with every _redirects rule before the rules in netlify.toml. Therefore, if both files contain a rule for /docs, the _redirects destination is selected before Netlify examines the configuration rule.

The rule order inside each source also matters. In _redirects, each rule occupies its own line. In netlify.toml, each redirect is an array-of-tables entry, and the entries form the configuration sequence. A later rule cannot replace an earlier matching rule.

# _redirects
/docs  /from-file

[[redirects]]
from = "/docs"
to = "/from-config"

For a request to /docs, the _redirects rule is encountered first. Netlify's own example shows the same first-match behavior with two identical source paths: the second rule never triggers because the previous rule matches first.

Why should a specific rule come first?

Matching is sequential, so a broad rule can take a request before a later exception. Netlify illustrates this with /jobs/customer-ninja-rockstar followed by /jobs/*. The exact path is listed first, while the splat handles the remaining paths under /jobs. If the exact path is placed after the splat, the splat is the first matching rule and the later exact rule is skipped.

The same ordering applies to conditions attached to rules. The redirect options documentation includes country, language, cookie, and role conditions, and its language example places the en-us rule before the broader en rule. The first reported browser language is used for language-based matching, regardless of quality weighting.

How do existing files affect the result?

Rule precedence and file shadowing are separate checks. By default, Netlify treats a same-site redirect as a fallback. Its request-chain documentation describes a rule from /foo to /bar as serving /bar when /foo does not match existing content. Static files are matched against the URL path, including files such as about.html and about/index.html for an /about request.

To make the redirect apply when a source file exists, use the forced form documented by Netlify:

/best-pets/dogs  /best-pets/cats.html 200!

[[redirects]]
from = "/best-pets/dogs"
to = "/best-pets/cats.html"
status = 200
force = true

The two forms express the same force setting for their respective sources. Netlify says the forced example applies even when /best-pets/dogs/index.html exists.

What happens before redirect rules?

Redirect precedence begins after earlier request-chain stages. Netlify's redirects overview states that edge functions are processed before redirects. The request-chain documentation places redirects after serverless function evaluation and before static-file matching, and says that a request continues when no redirect rule matches. An edge function can therefore return a response before the redirect sequence is reached.

Related terms

• How do I add redirects with Netlify's _redirects file?
• How do I make a Netlify redirect override an existing file?
• How do I redirect a URL directory on Netlify?

FAQ

Does netlify.toml override _redirects?

No. Netlify processes _redirects rules first. When both sources contain a matching rule, the earlier _redirects rule wins.

Can a later specific rule override an earlier wildcard?

No. The first matching rule stops the search. Put the specific path before the wildcard or splat rule.

Why does a matching redirect leave the existing page in place?

The default same-site behavior is a fallback that allows existing content at the source path to shadow the redirect. Use ! in _redirects or force = true in netlify.toml when the redirect must apply over that content.

Sources

1. Netlify, "Redirects and rewrites", 14 July 2025
2. Netlify, "Redirect options", 17 September 2026
3. Netlify, "Request chain", 18 March 2026

---

Check how a page reads to answer engines. Open the GEO score analyzer