Troubleshooting Web Elements
This guide helps you diagnose and resolve issues with Basis Theory Web Elements.
Need help? If you can't resolve your issue using this guide, our support team is ready to help at support@basistheory.com. See the Getting Support section for details on what information to provide.
Find immediate solutions to common problems below:
🔍 Common Error Messages
- "Element is not mounted" → Check DOM lifecycle
- "Timeout while resolving element values" → See value resolution
- "Failed to communicate with Basis Theory Elements" → Check initialization
- "Element was removed from the DOM" → Fix DOM removal issues
- "CORS error" or "Failed to fetch" → Network troubleshooting
- "Element mount timeout" → Mount timeout solutions
- "No route found for element of type..." → Reference errors
📱 Visual Problems
- Elements not appearing → Check initialization
- Elements disappearing → Check DOM lifecycle
- Elements look wrong in mobile WebViews → WebView guidance
🔄 Tokenization Problems
- Validation errors → Value resolution issues
- Timeouts during submission → See value resolution
- API errors → Network troubleshooting
- Inconsistent tokenization failures → Browser compatibility
- Corporate firewall issues → Network restrictions
Framework-Specific Considerations
Server-Side Rendering (SSR)
Important: Basis Theory Elements is designed to run exclusively on the client-side and cannot function properly in SSR environments.
Elements cannot be initialized during server-side rendering because:
- It needs access to browser APIs like DOM, postMessage, and localStorage
- It creates secure iframes that must load in a browser context
- It requires real-time user interactions that aren't available during SSR
Common pitfalls:
- Initializing BasisTheory during build or server render phase
- Not properly guarding code with browser environment checks
- Confusing hydration errors that seem unrelated to Elements
In frameworks like Next.js, be aware that using getStaticProps or getServerSideProps to fetch data related to Elements may lead to issues since Elements requires client-side initialization. Plan your data fetching strategy accordingly.
Network & Security Challenges
Ad Blocker Detection
Ad blockers and privacy extensions can block Elements from loading properly as they may:
- Block the loading of third-party iframes
- Prevent cross-origin communication
- Block scripts from domains they categorize as trackers
- Interfere with
postMessagecommunication
Many users won't realize they have ad blockers or privacy extensions active, especially if installed by their employer.
Signs of ad blocker interference:
- Elements containers remain empty with no errors in the console
- Console errors about script loading failures
- Missing network requests to basistheory.com domains
- Tokenization attempts that silently fail
- Messages like "Failed to load resource" for basistheory.com domains
User-Friendly Messages:
When an ad blocker is detected, consider showing a user-friendly message that:
- Clearly explains that an ad blocker has been detected
- Informs users that it may interfere with the secure payment form
- Provides simple steps to temporarily disable their ad blocker
- Reassures users that you don't show ads, but use technology that ad blockers might restrict
- Uses a noticeable but non-intrusive design with appropriate warning styling
Detection and recovery:
try {
const bt = await basistheory("<YOUR_API_KEY>");
// Elements initialized successfully
} catch (error) {
if (error.message.includes("Elements did not load properly")) {
// Likely ad blocker interference
showAdBlockerWarning();
} else if (error.message.includes("Unable to load the Elements script")) {
// Network or browser extension interference
showNetworkTroubleshootingMessage();
} else {
// Other initialization error
console.error("Initialization failed:", error);
}
}
Corporate Network Restrictions
Enterprise environments often implement strict network policies that can prevent Elements from functioning:
Common corporate restrictions:
- Blocking outbound requests to third-party domains
- TLS inspection that breaks secure iframe communication
- Internal proxies that modify request headers
- Network-level content filters that block iframe loading
- Intrusion prevention systems flagging cross-origin communication
- Data Loss Prevention (DLP) tools intercepting form inputs
Solutions:
- Whitelist ALL of these domains in your firewall:
*.basistheory.com*.browser-intake-datadoghq.com(for telemetry)
- If you're in a restricted network environment, consider implementing a retry mechanism
- Work with your network security team to allow cross-origin iframe communication
- Test in environments with similar network restrictions before deploying to production
Content Security Policy (CSP) Requirements
Web Elements requires specific CSP directives to function properly.
Required CSP directives:
<!-- Required CSP directives -->
<meta http-equiv="Content-Security-Policy"
content="frame-src https://*.basistheory.com;
script-src https://*.basistheory.com;
connect-src https://*.basistheory.com" />
If you serve Elements from a custom domain, include that domain in the same directives. The custom domain must use one subdomain label before your root domain, such as elements.yourcompany.com or js.yourcompany.com; bare root domains, such as yourcompany.com, and nested subdomains, such as pay.js.yourcompany.com, are not supported.
Elements also sends a frame-ancestors policy on iframe responses. For a custom domain, that policy allows the custom hostname, the root domain, and any subdomain under that root to embed Elements. For example, Elements served from js.yourcompany.com can be embedded by pages on yourcompany.com, js.yourcompany.com, and checkout.yourcompany.com. Embedding from unrelated origins is blocked.
Optional Sources
The directives mentioned above are essential for the SDK to work properly. However, you may also need to include the following sources that support our services:
Datadog
Datadog is used by BasisTheory for logging and debugging errors. If you don't allow the connection to Datadog in your CSP, it may be more difficult for Basis Theory to help with issues.
To allow the connection to Datadog, add the following directive to your CSP:
connect-src- https://*.browser-intake-datadoghq.com
Trusted Types
If you are using Trusted Types, you must allow dynamic script loading from the https://js.basistheory.com origin. This should be done BEFORE initialization.
// Must be executed BEFORE initializing the SDK
trustedTypes.createPolicy("default", {
createScriptURL: (input) => {
if (new URL(input).origin === "https://js.basistheory.com") {
return input;
}
return undefined;
}
});
Common CSP Errors
The setup above is recommended to avoid errors similar to these: