Last reviewed by Netlify Support in October 2024
Introduction
You’ve put blood, sweat and tears into 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
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 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.
Single-Page Apps
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.
Splats
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 /blog/article1 and /docs/contact/form would redirect to /blog/contact/form, etc.
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.
Role-Based Redirects
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 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!
Further guidance and use cases can be found in the Netlify Docs.
Internal Proxies (Netlify-to-Netlify)
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
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 _redirects or netlify.toml rules we processed.
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 _redirects or netlify.toml file(s) or they were not syntactically correct. Let’s 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 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
netlify.tomlfile
[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.
Your framework may not like a file without a filetype
In these instances, you can rename _redirects to _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 _config.yml.
include: [_redirects]
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.
Understanding shadowing
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
The _redirects file is read before the netlify.toml file. Thus, rules in the _redirects file will trump any rules in the netlify.toml file.
Both 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 /blog/* before /*). 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
Using the 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:
_redirects_en,_redirects_deand_redirects_fr,_redirects_prodand_redirects_devetc.
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
More information regarding deploy contexts and syntax can be found in the Netlify Docs or in this blog post around selective config per-build.
Still struggling?
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.