Skip to content

A Developer's Guide to Setting Up Squarespace Redirects

4 min read
Squarespace logo

Earlier this week, I was tasked with transferring some Apache page redirects to a new website on Squarespace. This was my first encounter with the website builder. While setting up page redirects was fairly simple, I did encounter a few issues and the errors Squarespace supplied were not the most helpful; so I am going to share what I learnt for anyone else who hits a similar stumbling block.

Creating redirects

Squarespace refers to redirects as 'URL mappings' and these are configured within your website's control panel under 'Settings > Advanced > URL Mappings'.

The format for a redirect rule in Squarespace is really simple:

/old-url -> /new-url 301

There are just four parts to the redirect rule, all of these must exist: the original URL, the arrow characters ->, the new URL, and finally the server response code.

Squarespace allows us to create both permanent (301) and temporary (302) redirects. Just use the corresponding server response code at the end of the rule. Most of the time you will probably want to set permanent redirects as shown in the example rule above.

Troubleshooting our issues

When we were setting up our redirects, we parsed the original Apache rules and attempted to convert them to the Squarespace format. However, when we imported these we hit the following error message when attempting to save the new URL mappings:

An unexpected error happened when saving your data.We don’t allow unlimited rules. If you have more then 5000 rules, that is most likely the cause.

While we had a lot of rules, we were nowhere near 5,000 redirects, so this error message wasn't particularly helpful to us. To add to the confusion, the documentation states: "The URL mappings field has a limit of 400 KB, which is usually around 2500 redirect lines." Again, we were still nowhere near this number of rules and definitely below 400 KB.

We ended up adding and saving the rules in small chunks until the error message started to show. This revealed four different problems with the rules being imported.

Issue 1 - Redirects to self

There were a couple of redirect rules in the supplied files that were redirecting to themselves. This meant we were attempting to create new rules like the following:

/old-url -> /old-url 301

This is clearly redundant and just needed deleting.

It's good that Squarespace is preventing rules like this from being created; however, it would have been nice to have had a more descriptive error message.

Make sure you remove all rules that redirect to self.

Issue 2 - Regex redirects

In Apache, we can write redirect rules that represent a collection of URLs by using a regular expression.

RewriteRule ^articles/(.*)$ /blog/$1 [R=301,L]

These had been missed when we parsed the redirects and converted them to the Squarespace format. To fix, they needed rewriting like this:

/articles/[name] -> /blog/[name] 301

Make sure all your rules use the Squarespace regex format.

Issue 3 - URLs containing spaces

Although it is generally a bad idea to have spaces in a URL, it is possible. Some of the rules being imported contained them, and the original Apache redirects looked like this:

Redirect 301 "/files/our services.pdf" /services

Squarespace will interpret any space in the rule as a separator of the rule parts. Therefore, we needed to rewrite this rule with the space character encoded as %20:

/files/our%20services.pdf -> /services 301

Make sure all your rules only use space characters to separate the rule parts, and that all spaces in URLs are replaced by the encoded character %20.

Issue 4 - Bad formatting

Finally, some of the redirects had issues with the spacing of the new rule. For example, in one case we were missing a space before the arrow characters ->:

/old-url-> /new-url 301

The documentation seems to imply we should be getting an 'Invalid mapping: Not enough parts' error here, but that wasn't the case.

Make sure all your rules are made up of the four parts with a space character between them.

Final words

Once we had identified the issues they were very quick to resolve. It is just a shame that the validation error message hadn't been more descriptive over the cause of the issue.

Hopefully this blog post will help anyone else who gets the error we had.

If you are setting up redirects in Squarespace using their URL mappings, just remember to test your redirects after you've saved them to ensure they work. Also, remember Squarespace will only redirect from the old URL if the original page has been deleted or disabled. The redirect is only implemented if the old URL would normally serve a 404 page not found error.

© 2024 Andy Carter