Common Issues

Illustrated drawing of Amadeus Maxmimilian StadlerIllustrated drawing of Amadeus Maxmimilian Stadler

Amadeus Stadler

Last updated February 17, 2023

In this article, you’ll learn about some common issues that can come up while implementing and working with the real-time preview feature in Mattrbld—and what you can do in order to mitigate them.

Setting the Correct Security Headers

The preview page is opened in an iFrame when it is being shown within the Mattrbld content editing UI. This means that it needs to be allowed to do so.

If your preview page doesn’t load at all from within the Mattrbld UI, you may have to check that your X-Frame-Options and Content-Security-Policy HTTP headers are set up correctly to allow your preview page to be opened within an iFrame on the Origin of your Mattrbld instance.

The X-Frame-Options header is obsolete and should be replaced with an appropriate Content-Security-Policy header.

A correct CSP header may look like this:

Content-Security-Policy: frame-ancestors 'self'

You can learn more about these headers on MDN:

Caching Issues

Depending on the caching settings of your server, the preview iFrame might load an outdated version of the preview page with no obvious way to clear the cache and reload the page.

This may lead to Mattrbld being unable to connect to the preview, prompting you to check whether the preview page implements the preview protocol correctly.

If you have the option, you could always set the Cache-Control HTTP header of your preview page to no-cache to avoid this issue, or, if you cannot or don’t want to change the cache control header, you can fall back to manually appending a random query string such as ?rand=123 to your preview URL in the General Settings tab.

Future versions of Mattrbld may automatically add a random query for “cache-busting” purposes on the first re-try, but this is not implemented at the moment.

You can learn more about Cache-Control on this article from MDN.

Refreshing the Preview Page

Sometimes you may want to simply reload the preview page without having to open and close the preview itself. You can do so by right-clicking somewhere on the preview page and selecting “Reload frame” (or the equivalent of your browser). If the preview protocol is implemented correctly, Mattrbld should be able to reconnect to the page after a refresh.


This article concludes the section on real-time previews in Mattrbld. In it, you have learned how previews work, what limitations they have, how to implement the preview protocol itself and its optional features, as well as what can go wrong and how to fix it.

In the final content section of this documentation, you will find all the necessary information you need to host your own instance of Mattrbld.