Troubleshooting

Start with the error requestId, connection ID, current connection state, and the exact domain. Never collect or log API keys, browser tokens, webhook secrets, or provider credentials.

The dialog does not open

1. Confirm the browser supports fetch, Web Crypto, and native <dialog>.
2. Confirm domain0.connectDomain() runs in browser code, not during server rendering.
3. Parse the session response with the exported Zod schema.
4. Verify the same-origin bridge route is reachable.
5. Inspect a caught Domain0TransportError, Domain0ProtocolError, or Domain0Error.

Unauthorized or forbidden

• Keep the platform API key on the server.
• Issue a fresh connection token for the exact connection being opened.
• Bind the token to the browser's exact origin, including scheme and port.
• Do not reuse production keys or connections across applications.
• Keep browser tokens in memory and refresh them through your authenticated server.

Provider detection needs input

Detection can produce several candidates or no stable public identity. This is not an integration failure. Domain0 Connect shows the provider picker and continues through the selected provider's safest available path.

Provider authorization fails

• Let the customer retry authorization with a current provider credential or consent session.
• Confirm popups and provider redirects are not blocked by the host application.
• Use guided setup when automatic authorization is unavailable.
• Never ask the customer to send provider credentials to your support team.

The connection remains pending

DNS answers can differ while caches expire. Domain0 checks the authoritative nameservers and activates only after every required record matches.

• Keep the saved connection ID and reopen the same connection.
• Confirm the record was added to the authoritative provider, not only the registrar.
• Confirm the host is relative to the connection domain.
• Compare type, value, MX priority, and trailing-dot normalization.
• Wait for the previous TTL when an older value was recently replaced.

Existing records conflict

The automatic flow displays the exact proposed plan. A destructive replacement requires separate confirmation. If the customer cannot approve it, close the flow, update your product's intent, or use a separate host that does not conflict.

Webhook verification fails

Read the untouched request bytes before parsing JSON. Pass the original headers and a 32-byte secret selected by signature key ID to verifyDomain0Webhook(). See Webhook verification.

Useful support details

Share only:

• Error requestId
• Connection ID
• Domain
• Approximate timestamp and timezone
• Current state and provider name
• Browser and application origin

Redact all credentials and tokens.