How Do I Troubleshoot Issues When Deploying Global Templates in Piano?

Introduction

Piano's Global Templates feature enables publishers managing multiple brands or applications under one umbrella to create templates centrally and deploy them across all connected applications at once. This eliminates the need to manually duplicate template work for each application and ensures brand consistency at scale.

However, deploying global templates introduces additional complexity compared to single-application template management. Issues can arise from misconfigured settings, unpublished template versions, caching across multiple CDN layers, browser or network restrictions, and propagation delays to child applications.

Prerequisites for Global Template Deployment

Before troubleshooting, confirm that the foundational requirements for global template deployment are in place. Many deployment failures trace back to missing prerequisites.

Verify Linked Applications

Global templates deploy across linked applications. Confirm that:

• All target applications are properly linked to the parent application (accessible via a drop-down menu from the top right corner).

• The linked applications are in the same environment (EU or US) as the parent application.

Template Types and Preview Support

Not all template types support dashboard previews. Before troubleshooting a "blank preview" as a deployment failure, confirm whether your template type generates a preview:

Common Deployment Symptoms

Use this section to match your symptom to the most likely cause, then proceed to the corresponding troubleshooting step.

Deployment Stuck in "Deploying"

The deployment status shows "deploying" indefinitely without completing.

• Likely causes: Transient UI/session issue, browser cache corruption, or a platform-side bug.

• Start with: This section (browser/session reset), then the following section if it persists.

Template Not Appearing in Child Applications

The template deploys successfully from the parent application but does not appear in one or more linked child applications.

• Likely causes: Application not properly linked, AID/environment mismatch, template not published before deploying globally, or propagation delay.

• Start with: This section, then this section.

Preview Blank or Showing Outdated Content

The template preview in the dashboard is blank (white screen/empty iframe) or shows an old version of the template code.

• Likely causes: Unsupported template type, missing offer term, browser extensions blocking the preview iframe, caching, HTTP/3 (QUIC) protocol issues, or the edited version was not published.

• Start with: This section, then this section through the following section.

Brand-Specific Values Not Populating

The global template deploys but brand-specific placeholder values are not being replaced in child applications.

• Likely causes: Brand-specific fields not defined in the Global template configuration, child application missing required field mappings, or propagation delay.

• Start with: This section.

Step-by-Step Troubleshooting

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

Rule Out Browser and Session Issues

These are the quickest checks and resolve the majority of preview and deployment UI problems.

1. Try Incognito/Private mode.

2. Disable browser 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. Navigate to: edge://settings/content/cookies/siteData?searchSubpage=piano

2. Click Remove all shown.

3. Log back in to the Piano dashboard and retry.

Chrome-Specific Cleanup

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

2. Click Delete displayed data.

3. Log back in to the Piano dashboard and retry.

Verify Template Publish Status

A common cause of deployment issues; especially when templates don't appear in child applications or preview shows old code, is that the template version was edited but not published.

1. Open the global template in the Piano dashboard.

2. Check the version history and confirm the version you intend to deploy is marked as published.

3. If the latest changes are in a draft state, publish the template before attempting global deployment.

4. After publishing, if the preview still shows old code, make a small edit (e.g., add a space), save, remove the edit, and save again to force a preview refresh.

Account for Caching and Propagation Delays

Global template changes may take additional time to appear across all linked applications due to multi-layer caching and propagation.

Disable HTTP/3 (QUIC)

In some environments, HTTP/3 (QUIC) can prevent preview content from loading. This affects both single-application and global template previews.

Retry the preview and deployment after disabling.

Check Network and Security Tooling

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

1. Try disconnecting from VPN and retesting.

2. Ask your IT/security team to allowlist the following Piano domains (adjust for your region):

Use Browser Developer Tools

When the issue persists after all previous steps, open browser Developer Tools (F12 or Ctrl+Shift+I) and inspect:

• Console tab: JavaScript errors, blocked requests, Content Security Policy (CSP) errors

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

Capture the following diagnostics for support escalation:

• A HAR file recorded while reproducing the issue

• Screenshots with Console and Network tabs visible

• A short screen recording showing the reproduction steps

Troubleshooting a Stuck Global Deployment

If your global template deployment is stuck in a "deploying" state and does not complete:

1. Clear browser cache and cookies, log out of the Piano dashboard, and log back in.

2. Stop and restart the deployment process if the UI provides this option.

3. Test in another browser or Incognito mode to rule out session corruption.

4. Verify the deployment is not partially complete, check each linked child application to see if some received the template while others did not.

5. If the deployment remains stuck, collect the following information before contacting support:

   • Exact time of occurrence

   • Template name, version, and type

   • List of target linked applications (with AIDs)

   • Whether the deployment is stuck for all applications or only specific ones

   • Screenshots of the deployment status screen

   • Console and Network logs (and HAR file if possible)

Validating Cross-Application Deployment

After deploying a global template, validate that the deployment succeeded across all target applications.

Checklist Per Linked Application

For each linked child application, verify:

1. The template appears in the child application's template list.

2. The template version matches the published version from the parent application.

3. Brand-specific values are correctly populated (not showing placeholder tokens).

4. The template renders correctly in preview (for supported template types) or on-site.

5. Any associated offer and terms are correctly configured in the child application (for offer templates).

Application ID and Environment Mismatch

A common cause of cross-application deployment failures is an AID or environment mismatch:

• Ensure the parent and all child applications use the same environment (all EU, AP, AU or all US).

• Verify that the AID referenced in each linked application is correct and active.

When to Contact Support

Contact Piano Support if:

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

• Template updates are not visible in child applications after 30+ minutes

• Global deployments remain stuck in "deploying" after browser/session troubleshooting

• Brand-specific values fail to populate despite correct Global template configuration

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

• Deployment succeeds for some linked applications but fails silently for others

Last updated: June 26, 2026