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. |
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. |
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. |
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. |
| 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 instead. |
Cloudflare ... request failed (403) | Give the token the permissions in 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. |
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. |
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. |
| 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. |