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!
Ensure you’ve followed the correct guidance
Your first port-of-call should always be the Netlify Docs. Our redirects and rewrites document covers a broad range of use cases, from status codes to proxying another service and everything in between.
Ensure you’re using the correct syntax
It’s super important to ensure that you’re using the correct syntax for what you’re trying to achieve, whether you’re using a dedicated
_redirects file or plonking your redirects in to a
netlify.toml file. All of our redirect options, and respective syntax, can be seen here.
That said, without a shadow of a doubt, we see most users stumbling over single-page app redirects, splats, role-based redirects and query parameters.
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. Never fear: there’s a guide for that.
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
It’s important to note that 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 String Parameters
Query strings are now automatically passed to our redirect engine. This change was made in January 2021. Therefore, if you are attempting 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!
My redirects are still not working
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 we processed, since a leading cause of redirects failures is a misnamed or mislocated or otherwise missing
I’m seeing 0 rules being deployed
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. Below we run through some common causes for this.
Your framework may not like seeing files in your publish directory before being built
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 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
netlify.tomlfile, under ‘build’
[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 update the
&& cp _/redirects dist/_redirects command with your file name and publish directory.
Your framework may not like a file without a filetype
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.
Your framework may not automatically include files which start with an underscore
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
My rules are being deployed but they’re not executing
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.
Order of execution
_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.
_redirects and netlify.toml do not support fallback rules
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
/*). More information can be found in the Netlify Docs.
Rules are being deployed and being executed for every context… and I don’t want them to!
This sounds like a job for context-specific rules!
Separate _redirects files for separate contexts or branches
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.