How Do I Troubleshoot Template Preview and Update Delays in Piano?

Introduction

Template preview, deployment, and update issues in the Piano dashboard can stem from a variety of causes, ranging from unsupported template types and browser quirks to caching layers and corporate network restrictions. This checklist walks you through each potential cause in a logical order, starting with the quickest checks and progressing to deeper diagnostics. By following these steps, you can resolve most issues independently or collect the right information for Piano Support to help you efficiently.

Confirm Preview Is Supported for Your Template

Before troubleshooting, verify that your template type actually supports dashboard previews. Skipping this step can lead to wasted effort investigating a "problem" that is actually expected behavior.

Templates Without UI Preview

The following template categories do not generate previews in the Piano UI:

• My Account templates

Offer Template Requirements

Offer templates require an associated offer with at least one term in order to render a preview. If no term exists:

• The preview may appear blank.

• Offer-related elements may be missing from the preview.

Action: Ensure your offer template has at least one term configured before attempting to preview.

Preview vs. Live Behavior Differences

Be aware that preview behavior may differ from your live site:

• The preview uses a default "registered user" context.

• If your template logic changes for new/anonymous users vs. registered users, the preview may not reflect the "new user" experience.

Common Symptoms and What They Usually Mean

Use the table below to quickly identify the likely cause based on the symptom you are experiencing.

Blank Preview (Empty Iframe / White Screen)

Most often caused by:

• Missing offer term(s) for an offer template

• Browser extensions (ad blockers, privacy tools) interfering

• Network/security tools blocking preview domains

• Browser protocol issues (HTTP/3 / QUIC)

Preview Shows Old Code (Changes Don't Appear)

Most often caused by:

• Caching (browser cache/cookies and/or edge/CDN caching)

• Preview/thumbnail generation lag (queued rendering)

• You edited a template but didn't publish the version you're testing

Step-by-Step Troubleshooting (Recommended Order)

Follow these steps in order. Each step builds on the previous one, starting with the fastest checks first.

Rule Out Browser/Session Issues

These are the fastest checks and resolve the majority of preview problems.

1. Try Incognito/Private mode.

2. Disable extensions, especially ad blockers and privacy/security extensions.

3. Try a different browser (latest versions recommended):

   • Chrome

   • Edge

   • Firefox

   • Safari

4. Ensure your browser and OS are up to date.

Edge-Specific Cleanup

1. Go to: edge://settings/content/cookies/siteData?searchSubpage=piano

2. Click Remove all shown.

3. Log back in and retry the preview.

Chrome-Specific Cleanup

1. Go to: chrome://settings/content/all?searchSubpage=piano

2. Click Delete displayed data.

3. Log back in and retry the preview.

Force the Preview to Regenerate

If the preview thumbnail or iframe appears "stuck":

1. Make a tiny HTML change (for example, add a space).

2. Click Save.

3. Remove the change and click Save again.

4. Reload the preview.

If your preview UI includes device controls:

• Change the device preview model, then use the reload/spinning arrows control to refresh.

Account for Caching/Propagation Delays

Template changes may take time to appear in preview and on-site due to caching and propagation.

Disable HTTP/3 / QUIC

In some environments, HTTP/3 (QUIC) can prevent preview content from loading. Disable it in your browser and retry.

Retry the preview after disabling.

Check Network/Security Tooling (Corporate Networks)

If you are on a corporate network, using tools like Zscaler, or connected to a VPN, the preview can fail due to blocked or rewritten requests.

1. Try disconnecting from VPN and retesting.

2. Ask your IT/security team to allowlist Piano dashboard and preview domains for your region.

Domains to allowlist (examples):

• https://dashboard-eu.piano.io/

• https://checkout-preview-eu.pianousercontent.io/

• Equivalent US, AP, AU domains if you are in another environment

Use Developer Tools to Identify Errors

When the issue persists after all previous steps, use browser Developer Tools to dig deeper.

Open Developer Tools (typically F12 or Ctrl+Shift+I) and check:

• Console: JavaScript errors, blocked requests, CSP errors

• Network: Failed requests (e.g., 404, 403, 5xx), stuck requests, redirects

If possible, capture the following diagnostics:

When to Contact Support

Contact Piano Support if:

• Preview remains blank after completing browser, network, and HTTP/3 checks

• Updates are not visible after expected propagation time (e.g., 30+ minutes live)

• You see repeatable errors in Developer Tools (Console/Network)

Include the following information in your support request:

Last updated: June 26, 2026