# Troubleshooting

This section covers common issues and their solutions when implementing Consent Pro on a custom site.

## Common Issues

### Content Security Policy (CSP) Errors

**Problem:** You see console errors like:

```
Refused to load the script 'https://api.consentpro.com/cdn/core/…' because it violates the following Content Security Policy directive: "script-src..."
```

**Cause:** Your website's Content Security Policy (CSP) doesn't allow the Consent Pro core script, its supporting scripts, or its API requests.

**Solution:**

1. **Identify where your CSP is configured:**
   - **Hosting provider or CDN:** the response-header settings (for example Cloudflare Transform Rules, Netlify `_headers`, Vercel `headers`).
   - **Your own server:** the web-server or framework configuration that sets response headers.
   - **A `<meta http-equiv="Content-Security-Policy">` tag** in the page template.

2. **Allow Consent Pro in both `script-src` and `connect-src`:**

   ```
   script-src 'self' https://api.consentpro.com [your other existing sources...];
   connect-src 'self' https://api.consentpro.com [your other existing sources...];
   ```

   Merge these sources into your existing directives instead of replacing the rest of your policy. If your policy uses nonces, hashes, or `strict-dynamic`, make sure the installed Consent Pro script is trusted by that policy.

3. **Redeploy your site** to apply the changes.

**Why this happens:** The browser loads the core script and supporting components from `api.consentpro.com`, then connects to the same origin for configuration and consent functionality. A restrictive CSP blocks those requests unless both directives allow the origin.

### Scans fail, stall, or come back incomplete

**Problem:** A scan fails, never finishes, or reports far fewer trackers than your site actually uses.

**Cause:** A security layer in front of your site is blocking or challenging our crawler, **ConsentPro Scanner**. This is most common with Cloudflare (Bot Fight Mode, Super Bot Fight Mode, or a WAF rule), but the same applies to any other protection layer — AWS WAF/CloudFront, Akamai, Fastly, Imperva, Sucuri, or a hosting provider's built-in bot protection. Because the scanner renders each page in a real browser engine, these systems classify its traffic as automated and stop it before it reaches your pages.

**Solution:** Pick whichever option fits your setup.

#### Option 1 — Allow our scanner (recommended)

Add `ConsentProScanner` to the allowed User Agents in your Cloudflare WAF settings. This lets our scanner through while keeping your site protected against everything else.

1. In the Cloudflare dashboard, go to **Security rules**.
2. Create a custom rule, for example `Allow ConsentPro Scanner`.
3. Under **When incoming requests match**, use field **User Agent**, operator **contains**, value `ConsentProScanner`.
4. Under **Then take action**, choose **Skip**, and select the bot protection features to bypass (Bot Fight Mode, Super Bot Fight Mode, or Managed Challenge, depending on what is enabled).
5. Move the rule to the **top** of the list so it runs before any rule that would block the request.

On other platforms the concept is the same: create an allow or bypass rule that matches requests whose `User-Agent` header contains `ConsentProScanner`. The scanner also sends the header `X-ConsentPro-Scanner: true`, which you can match on instead if your platform supports custom header conditions.

**warning Match on the token, not the full string**
Match on the `ConsentProScanner` token rather than the complete User-Agent string — the full string changes over time as the underlying browser version updates.


#### Option 2 — Temporarily disable the protection

If you would rather not keep a permanent rule, turn the protection off, run the scan, then turn it back on:

1. Disable bot protection (for example, Cloudflare's Bot Fight Mode) or switch your site to a permissive security level.
2. Run the scan from the Consent Pro app and wait for it to finish.
3. Re-enable the protection.

Scans run on demand or on a schedule. If you use scheduled scans, Option 1 is the better choice — otherwise each scheduled run will be blocked again.

Also check that your `robots.txt` does not disallow the `ConsentProScanner` user-agent (or all crawlers via `*`) on the paths you expect to be scanned.

For the full reference — how the scanner identifies itself, how it crawls, and cryptographic verification on Cloudflare Enterprise — see [ConsentPro Scanner](/scanner).

### SEO tools report an inefficient cache policy (Semrush, Lighthouse, etc.)

You install **one Consent Pro core script**. The runtime loads supporting Consent Pro components as needed, so performance tools may list more than one request from `api.consentpro.com`. That is expected. Many warnings usually come from other site assets. See [Performance & Privacy](/runtime/performance).

## Need More Help?

If you're still experiencing issues or have questions not covered here:

1. **Check the Documentation:**
   - [Performance & Privacy](/runtime/performance)
   - [JavaScript API](/runtime/api)
   - [HTML Attributes](/runtime/attributes)
   - [Events](/runtime/events)

2. **Community Resources:**
   - [Finsweet Forum](https://forum.finsweet.com/c/consent-pro/26)