Rewrites with empty query parameters

I’m having a hard time understanding why rewrites are working in a way that’s not matching my expectations.

I’m running a netlify dev server which is mimicking the rewrites functionality.

I have a URL with key/value parameters and I want to serve some static HTML pages I generate based on what the query parameters are.

For example, when I have a key and a value in the URL:

  • /search?color=red serves /search/_color/red.html
  • /search?category=100 serves /search/_category/100.html

And when I have only the key present in the URL, I want to serve the “index” page for that:

  • /search?color serves /search/_color/index.html
  • /search?category serves /search/_category/index.html

I have a redirects file that looks like this:

# For key + value pairs
/search color=:value /search/_color/:value.html 200
/search category=:value /search/_category/:value.html 200

# For keys _only_
/search color /search/_color/index.html 200
/search category /search/_category/index.html 200

This works almost as expected. But when I try /search?category rather than serving me the _category/index.html file, it serves the _color/index.html file.

I assume that has something to do with the fact that A) the parameter is empty/missing and B) it finds the color rule first in my redirects file?

What am I missing here? Is it wrong to assume that the mere presence of a matched query parameter should match to specific route? i.e. given this:

/path foo /foo.html 200
/path bar /bar.html 200

You would think /path?foo would serve you foo.html and /path?bar would serve you bar.html, but that doesn’t happen. In both cases foo.html is served. Why is that?

Is there a way to set this up such that it would go specific to generic in terms of what rewrite rules exist in the redirects file, eventually falling back to a generic index.html file, like this:

  • /path?foo=bar serves /path/_foo/bar.html
  • /path?foo serves /path/_foo/index.html
  • /path serves /path/index.html

I don’t see any mention of a form of query parameter redirect other than key=value in the docs (Redirect options | Netlify Docs).

You can also check the code for the redirect parser here (netlify-redirect-parser/line_parser.js at main · netlify/netlify-redirect-parser · GitHub), at a quick glance it seems to me it probably turns them into { [key]: undefined }

at a quick glance it seems to me it probably turns them into { [key]: undefined }

It does look that way, which is why I thought the mere presence of a specified query string key would result in the rewrite rule being processed. But what I’m finding is that is not the case. If you have a rule to redirect the /path?foo, Netlify’s redirects engine doesn’t seem to pick it up. It’s like the query parameter isn’t there at all, and the engine continues processing other rules.


I haven’t actually pushed anything to production and seen how it plays out on Netlify’s servers. But using netlify dev this is what I see:

Using the _redirects file and doing something like this:

/path foo /foo.html 200
/path bar /bar.html 200

Results in:

  • /path?foo - rewrite rule misses and I see a 404
  • /path?foo= - rewrite rule misses and I see a 404

But, when I use the netlify redirects playground and put in those exact same rules from the _redirects file, they get translated to this syntax for the netlify.toml file:

[[redirects]]
  from = "/path"
  query = {foo = ""}
  to = "/foo.html"
  status = 200
  force = false
[[redirects]]
  from = "/path"
  query = {bar = ""}
  to = "/bar.html"
  status = 200
  force = false

These rules result in:

  • /path?foo - rewrite rule misses and I see the 404
  • /path?foo= - rewrite rule catches and I see foo.html
  • /path?bar - rewrite rule misses and I see the 404
  • /path?bar= - rewrite rule catches and I see bar.html

Note the presence of the = sign makes the rule trigger—probably something to do with the differences in syntax between _redirects and netlify.toml.

That said, the docs for redirects in the netlify.toml file say this:

query: Query string parameters REQUIRED to match the redirect.

Note the emphasis on REQUIRED.

So perhaps there is no support for the mere presence of a query string parameter key—each query parameter HAS to have a key and a value, otherwise the redirects engine ignores it and moves on?

Your assertion is right on, @jimniels ! :100:

Netlify redirects need to have a key/value pair in the query string parameters. At the moment, you only seem to have a key which is unsupported configuration.

2 Likes