last reviewed April 2022
You’ve put blood, sweat and tears in to building an incredible static site with all the bells and whistles. However, you’ve configured some redirect rules and you’ve come unstuck… they don’t appear to be working!
It’s important that you’re using the correct syntax, whether you’re using a dedicated
_redirects file or a
netlify.toml file. All of our redirect options, and respective syntax, can be seen here.
That aside, let’s look at some common gotchas.
If you have a single-page React, Gatsby or similar site, it is likely that most of your requests should be sent to your
index.html file. This file then renders the appropriate content based on the URL, even though the single file is responsible for handling requests for most of your content. We have a guide for this.
A splat allows you to redirect traffic based on a URL’s suffix. For example:
/docs/* /blog/:splat 301
In this example,
/docs/article1 would redirect to
/docs/contact/form would redirect to
A splat can only be used at the end of a URL. If you’re trying to use a splat in the middle of a URL, you should take a look at placeholders instead.
A role-based redirect must either:
Use an asterisk, in order to gate access to an entire directory, e.g.
/gatedpages/* 200! Role=admin
Provide an explicitly defined rule, in order to gate a single page, e.g.
/gatedpage /gatedpage 200! Role=admin
Query strings are automatically passed to our redirect engine. To strip the query string from your redirect rule response, you should include a dummy query string in your to path, such as:
/* page=:page /:splat/:page?no-query-string 301!
Even if your sites use custom domains, ensure that you use the
.netlify.app domain for any proxy rewrite between your Netlify sites, like so:
/api/* https://another-netlify-site.netlify.app/api/:splat 200
If you think you’ve configured your redirects correctly but they’re still not working, take a look at your site’s deploy log.
In the deploy summary, we share how many rules we were able to process (denoted by the red box). If you’d like to see these processed rules, you can download a copy of your site, as-built, by clicking the icon in the blue box. In that download, you can review what
netlify.toml rules we processed.
If you’ve configured your rules but you see ‘0 redirect rules processed’ in your deploy log, this means that we did not see your
netlify.toml file(s) or they were not syntactically correct. Let’s run through some common causes for this.
As a rule of thumb, your redirect file should live alongside your
index.html file when your site is built. However, Jekyll and some React-based frameworks don’t like to see the file in your publish directory before the site is built.
Therefore, we need to update the build command to copy the
_redirects file from another directory to your publish directory.
Your build command will either be found:
- In your build settings, near the top of your build & deploy settings tab in our admin UI
- In your
[build] command = "npm run build && cp _redirects dist/_redirects" publish = "dist"
Any build command within
netlify.toml supersedes the build command within the admin UI.
In the above examples, we are taking the
_redirects file from the root of your site and copying it to the publish directory. You should retain your existing build command and append the
&& cp _/redirects dist/_redirects command and publish directory, ensuring you update this example with your file name and your publish directory.
In these instances, you can rename
_redirects.txt and update your build command. You can find the steps for updating your build command outlined in the section above.
Jekyll is one framework which will not automatically correctly manage files which start with an underscore. If you’re having trouble with Jekyll, you can add an include rule for the
_redirects file in your
Well, at least we can see the file! Now, it’s likely a matter of syntax and/or expectations.
We discuss shadowing in great depth within the Netlify Docs. In short, you can add an exclamation point to your HTTP status code (e.g.
301!) to force the rule, even if the original file is present. If the page or file you are redirecting from exists, your redirect rule will not work without the exclamation point.
_redirects file is read before the
netlify.toml file. Thus, rules in the
_redirects file will trump any rules in the
_redirects file and the
netlify.toml file are read from top to bottom. Therefore, more specific rules should sit at the top of your file and less specific rules should be at the bottom.
For example, a rule which redirects to
/blog/article should be above any rule to
/blog which should be above any rule to
There is one exception to this rule. Hostname redirects (e.g.
https://oldsite.com/* https://newsite.com/:splat 301!) should usually go at the top of your file.
As soon as a rule matches a file, no further rules for that file will be processed. Therefore, you should review your redirect files to ensure that there are no redundant or conflicting rules, and that the more specific redirects are above the more general ones in order (for instance, redirect for
/*). Though, it is possible to daisy-chain redirects. More information can be found in the Netlify Docs.
This sounds like a job for context-specific rules!
netlify.toml file, we are able to define different redirect rules for:
- Your production side
- Deploy previews
- Branch deploys
- Specific branches
To begin, you’ll need to create separate
_redirects files for each context or branch where you require different rules.
This could be:
For each context, within the
netlify.toml file, you can specify a unique build command. This build command can be appended with a command to copy your desired context-specific
_redirects file in to the publish directory. The syntax would appear as follows:
[context.YOURCONTEXT] command = YOURBUILDCOMMAND && cp YOURCONTEXTREDIRECT PUBLISHDIR/_redirects
At this point, we’ve covered all of the basics and some of the complexities. If you’re still struggling, I’d suggest that you check a couple of Netlify-hosted example sites for the framework you’re using. If all else fails, feel free to create a topic here in Community.