This page covers the most common errors when integrating Entri. For the complete API documentation, see the API Reference.
Initialization Errors
These errors occur when calling showEntri() or purchaseDomain() and prevent the modal from opening. The user sees “Entri is misconfigured. Please contact support for assistance.” Check browser console for the actual error.
showEntri() Errors
| Error | Console Message | Cause | Fix |
|---|
| Missing applicationId | ”Missing parameter: applicationId” | Config object missing applicationId | Add your applicationId from the dashboard |
| Invalid domain | ”This domain is invalid or uses an unsupported TLD (unlisted )“ | Domain doesn’t pass validation | Check domain format (examples of invalid: asdfasdf.asdfasdf, domain., 123.456) |
| Configuration error | ”Configuration error, please refer to the docs…” | forceManualSetup: true without prefilledDomain | Add prefilledDomain or remove forceManualSetup |
purchaseDomain() Errors
| Error | Console Message | Cause | Fix |
|---|
| Failed to fetch settings | ”Failed to fetch application settings” | API call failed (network error, invalid appId, or API down) | Check network, verify appId exists |
| Missing registrar | ”Your preferred registrar is missing…” | No preferred_registrar in config or app settings | Contact support to configure registrar |
| Unsupported registrar | ”Preferred registrar is not supported…” | Invalid preferred_registrar value | Use supported values: ionos, squarespace |
Modal Error Codes
These errors appear in the error object within onEntriClose and onEntriStepChange events when the user exits after seeing an error screen.
window.addEventListener('onEntriClose', (event) => {
if (event.detail.error) {
console.log('Error code:', event.detail.error.code);
console.log('Title:', event.detail.error.title);
console.log('Details:', event.detail.error.details);
}
});
| Code | Title | Description |
|---|
| AccessDeniedError | Invalid Permissions | Error when trying to set up domain, usually permissions issue |
| AuthCodeError | 2FA code invalid | Invalid two-factor authentication code |
| EmailNotVerifiedError | Unverified email | User needs to verify email in provider account |
| InvalidCredentialsError | Maximum login attempts exceeded | User should reset password or use manual setup |
| InvalidDomainError | Domain not found | Domain not found in provider account |
| InvalidNameservers | Invalid Nameservers | Domain nameservers are pointing to a third-party provider |
| GenericError | An error occurred | Generic setup error, user should retry |
| PurchaseDomainError | Purchase error | Error during purchase, refresh and retry |
| RegistroDomainInTransition | Domain in transition | Registro.br transitioning to advanced DNS (wait 5 min) |
| SessionError | Session Error | Session timed out, refresh page |
| SpfRecordsLimitError | SPF limit error | SPF record cannot have more than 10 domains |
| SpfRecordsLengthError | SPF length error | SPF record cannot exceed 255 characters |
| ProviderAuthenticationError | Error in provider authentication | Authentication issue with the provider account |
| ProviderError | Custom error in provider | Provider-specific error, such as a protected domain |
| UserInputTimeoutError | Session timed out | User did not enter credentials or 2FA in time, start over |
This list may not be exhaustive as some errors come directly from DNS providers.
Configuration Pitfalls
Common configuration mistakes that cause unexpected errors.
userId Mismatch
If you pass userId in your config object, it must match the userId used when generating the JWT token. A mismatch can cause misleading errors like “Invalid domain or DNS records”.
// ❌ Wrong: userId mismatch
const token = await getToken({ userId: "user-123" }); // JWT created with user-123
entri.showEntri({
applicationId: "...",
token,
userId: "user-456", // Different userId in config
dnsRecords: [...]
});
// ✅ Correct: userId matches
const token = await getToken({ userId: "user-123" });
entri.showEntri({
applicationId: "...",
token,
userId: "user-123", // Same userId
dnsRecords: [...]
});
validateDmarc with Existing Records
When validateDmarc: true is set and the domain already has a valid DMARC record, Entri will not modify it. However, if you also send a DMARC record in your dnsRecords array, this can trigger the manual setup flow.
| Scenario | Behavior |
|---|
validateDmarc: true, no existing DMARC | Entri creates your DMARC record |
validateDmarc: true, valid DMARC exists | Entri skips DMARC (no changes) |
validateDmarc: true, DMARC in dnsRecords, DMARC exists | May trigger manual setup flow |
This is intentional to prevent conflicts with existing email authentication. If you’re seeing unexpected manual flow redirects, check if the domain already has DMARC configured.
Debugging Tips
Check the Network Tab
- Open DevTools → Network tab
- Clear logs, then run the failing Entri setup
- Look for the
config or records API call
- Check the Response tab for error details
Non-blocking Console Warnings
Some console messages are warnings that don’t block the flow:
Invalid hex color whiteLabel.theme.fg: #xyz
Generating a HAR File
When reporting issues to support, a HAR (HTTP Archive) file captures all network requests and helps diagnose problems quickly.
Steps in Chrome:
- Navigate to the page where you’re experiencing the issue (don’t reproduce yet)
- Open Developer Tools: Right-click → Inspect, or
Ctrl+Shift+I (Mac: Cmd+Option+I)
- Go to the Network tab
- Ensure recording is active (red circle)
- Check Preserve log to capture requests across page reloads
- Click Clear to remove existing logs
- Reproduce the issue
- Right-click any request → Save all as HAR with Content
- Save and attach to your support request
HAR files may contain sensitive data (tokens, cookies). Review before sharing or use Entri’s secure upload option.
Need Help?
If you’re encountering an error not listed here, contact Entri support with:
- Error message or screenshot
- Browser console output
- The domain you’re trying to configure
