Troubleshooting
Causes and fixes for the most common problems when installing and using the SDK on your checkout.
First, open the checkout with your browser's developer tools and run Proteside.getStatus() in the console. The
result points to most of the problems below. See Verify the installation.
Installation
The dashboard only considers the SDK active when it receives events from real customers. Check, in this order:
- Is the snippet published? View the source of the published checkout page and search for
Proteside Start. Clear your site, theme and CDN caches. - Is it on the right domain? The snippet must be on the pages where the checkout actually runs, which may be on a different domain or subdomain.
- Has anyone opened the checkout? Open the page yourself and reload the dashboard after a few seconds.
- Does the SDK load? Run
Proteside.getStatus()in the console. If it errors, see the next item. - Are events going out? In the Network tab, requests to
app.proteside.comshould succeed. See The SDK runs, but nothing reaches the dashboard.
If the SDK Health page shows Only synthetic checks, Proteside's checker found the snippet, but no real customer has gone through the checkout yet.
shield.js didn't load. Common causes:
- the snippet isn't published, or only the bootstrapper was pasted;
- the Content Security Policy doesn't allow
https://cdn.proteside.cominscript-src(the console showsRefused to load the script); - an ad or tracker blocking extension blocked the file (test in a private window with no extensions);
- an optimization plugin changed or removed the tag.
Wait a few seconds: the SDK only finishes starting up after loading the store's configuration. If it stays false:
data-keyis missing on theshield.jstag. Without it, the SDK doesn't initialize and shows no warning.- The key has an invalid format. The console shows
[Proteside] Initialization failed silentlywithInvalid apiKey format. The key starts withpk_live_. - The tag was loaded as
type="module". Remove that attribute.
The SDK sends this warning, and getStatus().installationOrderValid becomes false, when there's any <script> on
the page before the snippet. The snippet must be the first script in the <head> for full coverage.
To check, open the published page's source (Ctrl+U) and see whether the <!-- Proteside Start --> block comes right
after the opening <head> tag, before any other <script>.
How to fix it:
- There's another script before the snippet. Move the snippet to the top of the
<head>and publish again. In Next.js, check the final tag order in the published page's source. - The snippet is old. Older snippets put the inline configuration in a separate
<script>tag. Copy the current snippet from Pages & Domains and replace the whole block. - The earlier script comes from the theme, a plugin or the platform itself and can't be moved. Protection keeps working, but with partial coverage. If you accept that, use Stop warning for this store on the alert itself. Only owners and admins see this option. To get the warning back, write to team@proteside.com.
Don't edit the snippet's content to make the warning go away: the inline rules block scripts from the very first byte of the page.
After fixing it, resolve the alert in the dashboard. If it doesn't come back on the next page visit, the order is correct.
This warning doesn't count toward the compliance status in PCI DSS Evidence.
The snippet has two parts, and both are needed for full coverage. If only the shield.js tag was pasted, or if an
optimization plugin turned the bootstrapper into an external or deferred file, paste the full snippet again and
exclude it from JavaScript optimizations.
To check, open the published page's source (Ctrl+U): between <!-- Proteside Start --> and <!-- Proteside End -->
there must be an inline <script> followed by the shield.js tag.
The shield.js URL (stable or latest channel) is written into the snippet. After changing the channel in
Payment protection, copy the snippet again from Pages & Domains and publish it.
If SDK Health shows more than one active version for several days, check that every page uses the same snippet. Right after an update, it's normal to see two versions because of browser and CDN caching.
Blocks and rules
Common console messages and what to allow:
| Message | What's missing |
|---|---|
Refused to load the script 'https://cdn.proteside.com/…' | https://cdn.proteside.com in script-src |
Refused to execute inline script | hash, nonce or 'unsafe-inline' for the bootstrapper |
Refused to connect to 'https://app.proteside.com/…' | https://app.proteside.com in connect-src |
The inline script message gives you the 'sha256-…' hash to include. See
Content Security Policy and headers.
With Allowed GTM containers filled in, Google Analytics 4 (G-…) and Google Ads (AW-…) tags can be stopped,
including when fired by GTM itself. The list only accepts GTM-… IDs, so there's no way to allow those IDs.
To fix it:
- In Payment protection, step What is normal at your checkout, empty the Allowed GTM containers list and click Save this step.
- Copy the snippet again from Pages & Domains and publish it. The list is also written into the snippet and keeps blocking at the start of the page load until you paste the snippet again.
The block applies in both protection modes, Monitor and Block.
- The script is in the page's HTML. In Scripts, it shows up with a note that it keeps loading from the HTML. Remove the tag at the source (HTML or theme).
- The rule is by Content hash. In-browser blocking applies to scripts loaded by address; inline scripts must be removed at the source. Use a Domain or Script URL rule.
- The rule is inactive. Turn the rule on in Rules.
- The change hasn't arrived yet. See A dashboard change didn't reach the checkout.
- In Rules, deactivate the rule that matches the affected script. Remember that a Domain rule blocks the entire domain and all its subdomains.
- Copy the snippet again from Pages & Domains and publish it: rules are written into the snippet.
- If you turned on Block mode, switch back to Monitor while you investigate.
Turning on Developer mode doesn't undo the blocks written into the snippet. See Pause and developer mode.
Data in the dashboard
That's expected. Every new script the SDK finds enters the inventory with the Needs review status and waits for your decision. To comply with PCI DSS 4.0, requirement 6.4.3, authorize each legitimate script with a justification or block the ones that shouldn't be there. You can authorize all first-party scripts at once and create policies to automate recurring decisions.
An authorized script goes back to Needs review when its content changes or when the authorization expires. See Scripts and Policies.
- Propagation time: changes reach the checkout within a few minutes. Wait and reload the checkout.
- Rules and GTM containers: these are written into the snippet. Paste the snippet again after changing them.
- Release channel: requires pasting the snippet again.
Check the responses to the requests to app.proteside.com in the Network tab:
| Response | Cause | What to do |
|---|---|---|
| 4xx error | A key or account problem. | Check SDK Health. If you rotated the key, copy the current snippet from Pages & Domains. If the subscription isn't current, see Billing. |
| Request blocked | CSP without https://app.proteside.com in connect-src, or an ad blocker. | See CSP and headers. |
A domain that had already sent events stopped receiving real sessions. The alert shows up within a day. Check that the snippet is still published (a theme or template update can remove it) and that the checkout had visits during that period. The alert resolves itself when traffic comes back.
Payment
- No customer has paid with Pix yet with the SDK on the page. The status changes when the SDK validates the first code.
- The Pix code doesn't appear as visible text. For full coverage, show the payment code as visible text or
provide it with
registerPaymentPayload(). See Payment integrity and Pix. - The snippet isn't on the page that shows the Pix code, for example a payment page separate from the checkout.
The recipient read from the code isn't among the Trusted recipients. Before treating it as an attack, check:
- whether the registered key is the same one that appears in the copy-and-paste code generated by your payment provider. Some providers generate the code with their own key, different from the store's key. In that case, confirm the recipient in Recipients seen at your checkout with It is my store;
- whether all the keys your store uses are registered and active.
If the code's key belongs neither to your store nor to your provider, treat it as an incident: open the alert in Alerts.
With a dynamic Pix generated by a payment provider, the code carries the provider's address instead of the store's key. Confirm the recipient in Payment protection → Recipients seen at your checkout with It is my store: the key the provider uses is often not the one you know. Recipient verification applies to codes that carry the recipient.
If the code includes the amount, also provide the expected amount with
Proteside.expectPayment().
Still having problems?
Gather the output of Proteside.getStatus(), the responses to the requests to app.proteside.com in the Network
tab and the address of the affected page, and write to team@proteside.com.