Errors Overview

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`

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

These indicate configuration issues but the modal will still open.

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

Get Started

Entri Activate

Entri Connect

Entri Sell

Entri Power

Entri Secure

Entri Monitor

Entri Network

Entri MCP

DNS Concepts

Reference

Legal & Security

Errors Overview

Initialization Errors

showEntri() Errors

purchaseDomain() Errors

Configuration Pitfalls

userId Mismatch

validateDmarc with Existing Records

Debugging Tips

Check the Network Tab

Non-blocking Console Warnings

Generating a HAR File

Need Help?

​Initialization Errors

​showEntri() Errors

​purchaseDomain() Errors

​Modal Error Codes

​Configuration Pitfalls

​userId Mismatch

​validateDmarc with Existing Records

​Debugging Tips

​Check the Network Tab

​Non-blocking Console Warnings

​Generating a HAR File

​Need Help?

Initialization Errors

showEntri() Errors

purchaseDomain() Errors

Modal Error Codes

Configuration Pitfalls

userId Mismatch

validateDmarc with Existing Records

Debugging Tips

Check the Network Tab

Non-blocking Console Warnings

Generating a HAR File

Need Help?