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

# Errors Overview

> Common errors and how to resolve them

This page covers the most common errors when integrating Entri. For the complete API documentation, see the [API Reference](/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 {tld})" | 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 {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.

```javascript theme={null}
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     |

<Note>
  This list may not be exhaustive as some errors come directly from DNS providers.
</Note>

## 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".

```javascript theme={null}
// ❌ 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   |

<Note>
  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.
</Note>

## Debugging Tips

### Check the Network Tab

1. Open DevTools → Network tab
2. Clear logs, then run the failing Entri setup
3. Look for the `config` or `records` API call
4. 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:**

1. Navigate to the page where you're experiencing the issue (don't reproduce yet)
2. Open Developer Tools: Right-click → Inspect, or `Ctrl+Shift+I` (Mac: `Cmd+Option+I`)
3. Go to the **Network** tab
4. Ensure recording is active (red circle)
5. Check **Preserve log** to capture requests across page reloads
6. Click **Clear** to remove existing logs
7. Reproduce the issue
8. Right-click any request → **Save all as HAR with Content**
9. Save and attach to your support request

<Warning>
  HAR files may contain sensitive data (tokens, cookies). Review before sharing or use Entri's secure upload option.
</Warning>

## 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