> ## Documentation Index
> Fetch the complete documentation index at: https://usefoil.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Checks and troubleshooting

> Understand the three checks and the statuses on a Foil first-party integration, and fix the common causes when a check, an install, or a page request fails.

Step 5 of the integration page shows three checks, and the page header shows the integration's status. This page explains what each check verifies, when it runs, and what to fix when it fails.

## The checks

| Check | What Foil verifies |
| - | - |
| **Domain verified** | The `_foil.<integration hostname>` TXT record has the integration's value, the integration hostname resolves to a public address, and no other Foil organization has verified the same integration URL. |
| **SDK loading** | Foil requests `<integration URL>/t.js` from the public internet. The response must have status `200`, carry no `Set-Cookie` header, and match the SDK release selected for the integration byte for byte. |
| **Secure cookie round-trip** | A browser request through the integration returned the continuity cookie that Foil set on an earlier response. |

Foil runs **Domain verified** and **SDK loading** when you select **Install integration** or **Start accepting traffic**, when you select **Re-check setup**, and regularly while the integration is installed. **Secure cookie round-trip** depends on real visitors. Load a page that runs the install snippet and reload it once. After the cookie check passes, it stays passed.

## Statuses

| Status | Meaning |
| - | - |
| **Ready to configure** | The integration exists but isn't installed. Foil rejects requests from its edge. |
| **Waiting for DNS** | Foil couldn't find the ownership TXT record yet, or the integration hostname doesn't resolve to a public address. |
| **Installing** | Foil is deploying the edge, or starting to accept traffic from an edge you run. |
| **Verifying** | The integration is installed and serves traffic. It moves to **Active** the next time the checks run after the cookie check passes. Select **Re-check setup** to run them right away. |
| **Active** | All three checks have passed. |
| **Needs attention** | An operation on an installed integration failed. The integration page shows the error. The integration keeps serving traffic unless **Domain verified** is failing. |
| **Draining** | You started removal. Existing sessions keep working for 24 hours, and new sessions fail. |
| **Removing**, **Removed** | Foil is removing, or has removed, its resources from your CDN. |

When you start an operation, the dashboard queues it, and you can leave the page. Foil retries temporary failures, such as DNS that hasn't propagated or a CloudFront distribution that is still deploying. An operation that hasn't finished after two hours times out and fails. Start it again from the integration page.

## Domain verified fails

| Cause | Fix |
| - | - |
| The TXT record is missing or hasn't propagated. The error reads `DNS verification is pending for _foil.<hostname>`. | Publish the record exactly as the integration page shows it, then select **Re-check setup**. |
| The record has the wrong name. Some DNS providers append the zone name to the name you enter, which turns `_foil.www.example.com` into `_foil.www.example.com.example.com`. | Enter only the part before the zone, such as `_foil.www`, if your provider appends the zone. |
| The record has the wrong value. | Copy the full value, including the `foil-verification=` prefix. |
| The integration hostname has no A, AAAA, or CNAME record, or one of the addresses it resolves to is private or reserved. The error reads `<hostname> does not resolve to a public IP address`. | Point the hostname at your CDN or edge with public DNS records. Every address the hostname resolves to must be public, so remove private or reserved answers even when other answers are public. Foil resolves the hostname from the public internet, so a record that exists only on an internal network doesn't count. |
| `Another Foil account has already verified this Integration URL.` | Contact Foil support to move the URL to your organization. |
| The check passed before and now fails. | Restore the TXT record. While ownership fails, the integration accepts no new sessions. Sessions already in progress keep working. |

## SDK loading fails

| Problem | Cause | Fix |
| - | - | - |
| The integration hostname's certificate isn't valid. | The certificate has expired, is self-signed, or doesn't cover the hostname. The error reads `<hostname> did not present a valid TLS certificate`. | Serve the hostname with a publicly trusted certificate that covers it. If your CDN is still issuing the certificate, Foil retries until the operation times out. |
| Foil can't reach the integration URL. | The request for `<integration URL>/t.js` was refused, reset, or timed out, because the edge isn't running or a firewall or IP allowlist blocks requests from the public internet. The error reads `Foil could not load t.js from <hostname>`. | Request `<integration URL>/t.js` from outside your network, and allow HTTPS requests from the public internet to the integration path. |
| The integration URL isn't serving the SDK yet. | `t.js` on the integration URL didn't return `200`. The edge isn't deployed yet, CloudFront is still propagating, a custom edge doesn't forward `/t.js`, or your site redirects the URL to another page or hostname. | Wait for the deployment to finish, or request `<integration URL>/t.js` yourself to see the status. Exclude the integration path from redirects. |
| The SDK response sets a cookie. | The `t.js` response included a `Set-Cookie` header. A load balancer, application, or security product in front of your site adds `Set-Cookie` to every response. | Exclude the integration path from anything that sets cookies. |
| The integration isn't serving its selected SDK release yet. | The `t.js` body differs from Foil's release. Your CDN served a cached copy or changed the JavaScript, for example by minifying it or injecting scripts. | Disable caching and content transformations for the integration path. |

## Secure cookie round-trip doesn't pass

| Cause | Fix |
| - | - |
| No browser has loaded the SDK through the integration yet. Pages still import `t.js` from `cdn.usefoil.com`. | Deploy the install snippet, load a page that runs it, and reload once. |
| The page imports `t.js` from somewhere other than the integration URL and doesn't set `endpoint`, so the SDK collects directly. | Set `endpoint` to the integration URL. See [Load the SDK from your domain](https://usefoil.com/docs/first-party/overview.md#load-the-sdk-from-your-domain). |
| Your edge drops the `Cookie` request header or the `Set-Cookie` response header. | Forward the continuity cookie and return `Set-Cookie` unchanged. See [Continuity cookie](https://usefoil.com/docs/first-party/edge-contract.md#continuity-cookie). |
| The browser blocks cookies for the site. | Test in a browser window with default cookie settings. |

## Installation errors

| Error | Fix |
| - | - |
| `The integration hostname must belong to the selected Cloudflare account and zone` | Select the zone that contains the integration hostname, and make sure the account ID matches. |
| `An existing Worker route overlaps this integration URL` | Remove or narrow the overlapping route, choose another path, or create a [Cloudflare integration with your Worker](https://usefoil.com/docs/first-party/deployments.md#cloudflare-with-your-worker) instead. |
| `Cloudflare ... request failed (403)` | Give the token the permissions in [Cloudflare requirements](https://usefoil.com/docs/first-party/deployments.md#cloudflare-requirements), then replace it under **Cloudflare token** on the integration page. |
| `An existing DNS record conflicts with <name>` | Foil doesn't overwrite DNS records. Fix the record yourself, or publish the TXT record manually. |
| `The integration hostname must be an alias on the selected distribution` | Add the hostname as an alternate domain name on the distribution, or select the distribution that has it. |
| `Existing CloudFront behaviors overlap the integration URL` | Remove the overlapping behavior or choose another path. |
| `Provider operation failed. Check account access and retry.` | On a CloudFront integration that Foil deploys, Foil couldn't assume the deployment role or call AWS. Compare the role's trust policy and permissions policy with the templates in step 2 of the integration page, including the external ID. On a custom integration, Foil has no account to access, so retry the operation, and contact Foil support if the error persists. |
| `CloudFront is propagating the adapter; verification will retry automatically` | No action needed. Foil retries until the distribution is deployed. |

## Errors on your pages

| Symptom | Cause | Fix |
| - | - | - |
| Requests through the integration fail with `401` and `auth.invalid_api_key`, but the key works when you load the SDK directly. | Either the key belongs to the other environment, such as a `pk_test_*` key on a **Live** integration, or the edge isn't sending a valid credential, integration ID, `Host`, or visitor IP. | Use a key from the integration's environment. For a custom edge, see [Rejections](https://usefoil.com/docs/first-party/edge-contract.md#rejections). |
| Requests fail with `403` and `auth.origin_not_allowed`. | The page's origin, or the site origin the edge sends as a fallback, isn't in the key's allowed origins. | In step 4 of the integration page, select **Add to allowed origins**, or add the origin or a `https://*.<domain>` entry to the key under **API Keys**. See [Serve several domains](https://usefoil.com/docs/first-party/multiple-domains.md). |
| `start()` rejects with `transport.upgrade_required` on every page load. | Foil refuses new sessions through the integration. The integration is draining, its ownership TXT record is missing, or the page runs an SDK release older than the integration's current and previous releases, for example a copy cached by your CDN or bundled into your code. | Restore the TXT record, serve `t.js` from the integration URL without caching, and reload. |
| The browser console reports a Content Security Policy violation. | The policy doesn't allow the integration origin or the inline install snippet. | See [Content Security Policy](https://usefoil.com/docs/content-security-policy.md#first-party-integrations). |
| Sessions report their network as unverified. | The network edge probe is blocked, usually by `connect-src`. Sessions still score. | Allow `https://*.e2.usefoil.com` in `connect-src`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.