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

last reviewed April 2022

Introduction

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

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!

A demo of the above rule in action can be seen here. 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

Build___deploy___Settings

  • In your netlify.toml file
[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 /*). Though, it is possible to daisy-chain redirects. 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 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.

I can't make redirects happen. I have read, I have tried and it did not work
Redirect not working - Netlify recognises the rule
Redirecting to parent directory
How to proxy POST Request in Netlify?
Nuxt redirects does not work
How to remove the cached redirect file in netlify follow up
Netlify.toml [[redirects]] rules not working as expected
Gatsby trailing slash redirection
404 redirects not working or conflicting
Redirect working except for root
Redirect file not processed
Redirect rule not works from external
Exclude a route when using wildcard *
I need some help to understand why redirects does not work as should in my react website
Redirect not fully-working in spite of following _redirects documentation
How to redirect?
301 error and multiple requests when _redirect file added
Need help with redirection
Redirect doesn't seem to be redirecting
"Looks like you've followed a broken link" when viewing site
How to remove the cached redirect file in netlify
How do I correctly get redirects working?
Redirect proxy domain/path to subdomain/path not working
Redirect all old urls to home
Trouble with query parameter in a redirect
404 per domain?
Intermittent issue with dynamic routes using Nuxt and NetlifyCMS
VueJS Route on Netlify
Preserve query parameters on redirect
Domain-level redirect in _redirects succeeds, but in netlify.toml fails with 500 error
Netlify Identity: How to redirect users to specific url after signup/login?
Redirects with parameters not working
_redirects syntax to allow access to all files of a certain type?
CORS proxy works on Netlify Dev but not when deployed
Netlify proxying redirect causing duplicated headers
Redirect rule in netlify.toml format
ReactJS / Auth0 - routing with netlify causing infinite loop (single page routing)
Setting up routing fo using Sanity CLI as a static subdirectory
Redirects of gh-hosted pages to custom domain
Redirect by country issue
Deployed my app and getting 404 page not found
Rewrite from a Netlify site to a NextJS site
NextJS redirect not working for static assets
Redirects dont work
[Support Guide] Compiled CDN Resources — start here!
Problem error 500
Redirects file _redirects not working for certain url instances despite having similar working implementations in file
Tailwind CSS is not working after deploying to Netlify
Reverse proxy with redirects is preserving query parameters on 302 response
Role based access struggles
Redirect from facebook with functions check is click from facebook urgent
Remove trailing query string from redirected URL
Redirect don't work when you visit your site for the first time
Redirect domain alias certificate issue
Using query parameters in a redirect
Redirects with role not working as intended
Netlify.toml redirects not working
Warning while parsing _redirects file
Redirect don't work when you visit your site for the first time
Redirects not working for second site
Redirect with query parameters not working
Redirect rules are not processed
Redirects using placeholder but the last placeholder has .html that I want to remove
Changes in _redirects
Redirects not working from outside of react website
_redirects directing a hole into my head
How do I host multiple React apps under single hostname?
Add a redirect for a URL path and all subsequent sub-paths
Proxy POST requests via netlify.toml redirects
Custom error page Next.js
Redirect url with one param to another url with a different param
Proxy File Shadowing _redirects not working. 404 on Nuxt SPA Bundle
Redirecting to another Netlify site's functions results in 502 in production
Redirects that are not case sensitive
Changes to Redirects with query string parameters are coming
Redirect only working without query params