Known problems and how to solve 

Assets from other hosts do not load 

Symptom: web fonts from Google Fonts, a library from a CDN or images from an external server are missing in the preview, while they work on the website. The console reports a Content Security Policy violation, not a CORS error.

Cause: the preview document inherits the Content Security Policy of the TYPO3 backend, which by default only allows assets from the backend's own host. Adding a CORS header does not help here, the browser refuses the request before it is sent.

Fix: serve the assets from your own host, or extend the backend policy for the hosts you trust with a Configuration/ContentSecurityPolicies.php in your site package:

<?php

use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Directive;
use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Mutation;
use TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationCollection;
use TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationMode;
use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Scope;
use TYPO3\CMS\Core\Security\ContentSecurityPolicy\UriValue;
use TYPO3\CMS\Core\Type\Map;

return Map::fromEntries([
    Scope::backend(),
    new MutationCollection(
        new Mutation(MutationMode::Extend, Directive::FontSrc, new UriValue('https://fonts.gstatic.com')),
        new Mutation(MutationMode::Extend, Directive::StyleSrc, new UriValue('https://fonts.googleapis.com')),
    ),
]);

See the Content Security Policy chapter of the core API reference for the details.

Fonts or scripts do not load 

Symptom: the preview uses fallback fonts, or with allowSiteScripts the site scripts do not run. The browser console inside the frame reports a CORS error.

Cause: web fonts and JavaScript modules are loaded as cross-origin requests from the frame. The web server does not send Access-Control-Allow-Origin: * for them. Look's own script is not affected, it is a classic script.

Fix: add the header for the path your frontend build lives in, see If your frontend uses web fonts.

SVG icons are missing 

Symptom: icons referenced as an external SVG sprite are blank. The console says "Unsafe attempt to load URL ... from frame with URL about:srcdoc".

Cause: <svg><use href="/icons.svg#play"> may only load files from the same origin, and the frame has none.

Fix: inline the SVG when rendering for the preview. A small view helper that reads the icon file and returns its markup does the job. Detect the preview context in your templates, for example with a flag your preview template sets, and switch between the sprite reference (frontend) and the inline markup (preview):

<f:if condition="{isBackendPreview}">
    <f:then>{my:svg.inline(path: 'EXT:my_site/Resources/Public/Icons/{name}.svg', class: 'icon')}</f:then>
    <f:else>
        <svg class="icon"><use href="{f:uri.resource(path: 'EXT:my_site/Resources/Public/Icons/{name}.svg')}#icon"></use></svg>
    </f:else>
</f:if>

Icons that are inlined in the frontend anyway need no change.

The preview appears three times 

Symptom: with Content Blocks, the whole preview is repeated three times.

Cause: Content Blocks renders backend-preview.html for the header, the content and the footer of the element.

Fix: use the Preview layout with a Content section, see Previews for Content Blocks.

Images are missing, "File ... does not exist" 

Symptom: the preview shows broken images or an error about a processed file that does not exist.

Cause: backend requests defer image processing to a later request. A frontend template that expects the processed file immediately (for example a custom picture renderer) does not get it.

Fix: set the fileProcessing aspect of the TYPO3 context to non-deferred (new FileProcessingAspect(false)) while rendering the preview, in the same wrapper that handles the visibility aspect.

A red callout instead of the preview 

Symptom: the page module shows "Preview could not be rendered" with an error message and a code.

Cause: rendering the frontend markup threw an exception.

Fix: in development context (or with backend debugging enabled) the callout names the problem, usually a missing partial, a wrong argument or a PHP error in a view helper; in production it shows only the error code and the details go to the TYPO3 log. Correct the template and reload the page module.

Nothing works in the standalone Install Tool 

The previews need the nonce of a backend request. The standalone Install Tool (/typo3/install.php) has none and does not render page module previews, which is expected.