Sync Fails Due to CORS Issues × Mattrbld

Unfortunately, using Mattrbld with many Git providers requires a proxy server to work around CORS issues. You can learn more about this topic in the article on how to host your own proxy server. This article will describe how to troubleshoot sync issues caused by the proxy server.

Identifying a CORS issue

As with any synchronisation issue, Mattrbld will notify you about it in one of two ways:

If you initiated the sync process that failed, you will immediately be shown a modal window containing the error message
If Mattrbld initiated the sync process, for example after opening a project, the status indicator in the project sidebar will turn red and show “error”. Clicking it will open the modal window with the error message.

The error itself might be different depending on what you were trying to do and whether your CORS proxy is configured as a local URL or a different (sub-)domain.

Here are some examples:

A Mattrbld error modal showing a SmartHTTPError message with some additional information that makes it clear the CORS Proxy URL was pointing at a HTML-page instead of a proper proxy server. — Example of a local CORS Proxy URL failing

A Mattrbld error modal showing a "Failed to fetch" error with the hint "Check your internet connection and make sure your CORS-proxy is set up correctly." — Example of a fetch error that could be caused by a faulty CORS proxy

While the first error makes it pretty obvious that the configured CORS proxy URL (a local path such as /corsprox) is serving an HTML page instead of passing through the request, the second error may also be caused by a spotty internet connection.

In both cases, try changing the CORS Proxy URL in the General Settings tab of the project settings to a proxy you know is working or spin up a local CORS proxy and insert a localhost-URL. If the sync proceeds without further errors after that change, something might be wrong with your usual CORS proxy.

Common Issues

There are a range of reasons why your CORS proxy may not work. Here are three most common ones.

Misspelt URL

The most basic reason why your sync may be failing with a CORS proxy issue is because the URL is misspelt in the project settings. So your first step of troubleshooting should always be to do double-check it.

If you’re running into these issues during the initial import of a project, either during onboarding or from the projects overview, you can specify a custom CORS proxy in the advanced settings and optionally set it as a default for future imports.

Relying on Third Party Servers

Everything you sync in Mattrbld passes through your proxy—including authentication credentials! This means you should completely trust it, which is best done if you’re the one hosting and thus controlling it.

If you do end up relying on a third party proxy server instead, you may never know when it may stop functioning. So if you do not host your own proxy server and notice sync issues because of your CORS proxy, try switching to a different one to see if the issues are resolved. If they are, you may have to contact the provider of your third party CORS proxy server to alert them to the issue, so they can fix it.

Misconfigured CORS Proxy Whitelist

Depending on how it’s set up, your CORS proxy server may only allow access from certain origins by setting the Access-Control-Allow-Origin HTTP header. In this case, you have to make sure that the instance of Mattrbld you’re using is hosted on one such origin.

If you’re hosting your own server and have recently switched from using the official Mattrbld instance to your own, you may also have to adjust the allowed origin of your CORS proxy server to reflect the origin of your Mattrbld instance.

The term “origin” refers to the full URL of a resource, including the protocol and port. So if your Mattrbld instance is hosted on mattrbld.example.com on port 4444, the origin is actually https://mattrbld.example.org:4444. You can learn more about it in this article on MDN.

Conclusion