[Support Guide] Making redirects work for you - troubleshooting and debugging

First Steps

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 and query parameters.

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. Never fear: there’s a guide for that.

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.

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.

Query String Parameters

Query strings are not automatically passed to our redirect engine. Therefore, they must be explicitly defined. For example:

/store post=:id  /blog/:id  301

In this example, /store?id=item1-article would redirect to /blog/item1-article, but the redirect would not happen UNLESS the post parameter is passed! Further guidance and use cases can be found in Netlify Docs.

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 we processed, since a leading cause of redirects failures is a misnamed or mislocated or otherwise missing _redirects file.

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

Build___deploy___Settings

  • In your netlify.toml file, 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 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_de and _redirects_fr,
  • _redirects_prod and _redirects_dev etc.

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.

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.