# Troubleshooting

> Causes and fixes for the most common problems when installing and using the SDK on your checkout.

URL: https://docs.proteside.com/en/docs/integration/troubleshooting

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](https://docs.proteside.com/en/docs/integration/verify).

## Installation
### The dashboard shows Proteside not detected

The dashboard only considers the SDK active when it receives events from real customers. Check, in this order:

1. **Is the snippet published?** View the source of the published checkout page and search for `Proteside Start`.
   Clear your site, theme and CDN caches.
2. **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.
3. **Has anyone opened the checkout?** Open the page yourself and reload the dashboard after a few seconds.
4. **Does the SDK load?** Run `Proteside.getStatus()` in the console. If it errors, see the next item.
5. **Are events going out?** In the **Network** tab, requests to `app.proteside.com` should succeed. See
   [The SDK runs, but nothing reaches the dashboard](#nada-chega-ao-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.

### window.Proteside doesn't exist in the console

`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.com` in `script-src` (the console shows
  `Refused 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.

### getStatus() shows initialized: false

Wait a few seconds: the SDK only finishes starting up after loading the store's configuration. If it stays `false`:

* **`data-key` is missing** on the `shield.js` tag. Without it, the SDK doesn't initialize and shows no warning.
* **The key has an invalid format.** The console shows `[Proteside] Initialization failed silently` with
  `Invalid apiKey format`. The key starts with `pk_live_`.
* **The tag was loaded as `type="module"`.** Remove that attribute.

### Installation order warning (INSTALLATION_ORDER_WARNING)

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](mailto: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**.

### Only the shield.js tag is on the page

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.

### I changed the channel and the SDK version didn't change

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
### The browser blocks Proteside (Content Security Policy)

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](https://docs.proteside.com/en/docs/integration/csp).

### GA4 or Google Ads stopped after enabling the GTM container list

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:

1. In **Payment protection**, step **What is normal at your checkout**, empty the **Allowed GTM containers** list and
   click **Save this step**.
2. 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**.

### I blocked a script and it keeps loading

* **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](#mudanca-nao-chegou).

### The checkout broke after creating a rule or turning on Block mode

1. In **Rules**, deactivate the rule that matches the affected script. Remember that a **Domain** rule blocks the
   entire domain and all its subdomains.
2. Copy the snippet again from **Pages & Domains** and publish it: rules are written into the snippet.
3. 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](https://docs.proteside.com/en/docs/integration/configuration#pausa-e-modo-desenvolvedor).

## Data in the dashboard
### Scripts show up as Needs review

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](https://docs.proteside.com/en/docs/guide/scripts) and [Policies](https://docs.proteside.com/en/docs/guide/policies).

### A dashboard change didn't reach the checkout

* **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.

### The SDK runs, but nothing reaches the dashboard

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](https://docs.proteside.com/en/docs/guide/settings/billing). |
| Request blocked | CSP without `https://app.proteside.com` in `connect-src`, or an ad blocker. | See [CSP and headers](https://docs.proteside.com/en/docs/integration/csp).                                                                                                                                                 |

### I got the SDK Silent alert

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
### Pix stays at WAITING in Payment Integrity

* **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](https://docs.proteside.com/en/docs/integration/payment-integrity).
* **The snippet isn't on the page that shows the Pix code**, for example a payment page separate from the checkout.

### Recipient does NOT match the trusted list

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**.

### Dynamic Pix shows up outside the trusted list

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()`](https://docs.proteside.com/en/docs/integration/javascript-api#expectpaymentexpectation).

## 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](mailto:team@proteside.com).
