Troubleshoot Auth0 Custom Domains Issues

May 20, 2026

Overview

Troubleshooting custom domains configured with Auth0-managed certificates involves verifying the provision status, addressing Domain Name System (DNS) or Certification Authority Authorization (CAA) record issues, and resolving common errors. Review the custom domain status and configure the DNS settings correctly to ensure successful verification and certificate provisioning.

Applies To

Auth0
Custom Domains
Troubleshooting

Solution

How is the custom domain provision status reviewed for troubleshooting?

Review the custom domain provision status using the Auth0 Command Line Interface (CLI) or the Management API by performing the following actions.

Auth0 CLI: Run the following command to list existing domains and their statuses.
```
auth0 domains list
```

Auth0 Management API: Send a GET request to the /api/v2/custom-domains endpoint.

curl -L -g 'https://<tenantDomain>/api/v2/custom-domains' \
-H 'Accept: application/json'

The response includes a list of the custom domains, including their status, verification.status, and if verified, their certificate.status.

{
  "custom_domain_id": "cd_9JPAp8JxtP0jvmbc",
  "domain": "yellow.acmetest.org",
  "primary": true,
  "status": "ready",
  "type": "auth0_managed_certs",
  "verification": {
    "methods": [...],
    "status": "verified",
    "last_verified_at": "2025-06-10T12:49:05Z"
  },
  "tls_policy": "recommended",
  "certificate": {
    "certificate_authority": "letsencrypt",
    "status": "provisioned",
    "renews_before": "2025-09-08T11:52:12Z"
  }
}

What occurs during the verification and certification processes when configuring an Auth0-managed custom domain?

Auth0 updates the status attributes during the verification and certification processes in the following ways.

Auth0 attempts to verify the DNS record for the provided custom domain when an Auth0-managed custom domain is first configured. Auth0 sets the initial custom domain status to pending_verification and its verification.status to pending.
Auth0 sets the custom domain verification.status to verified and its certificate.status to provisioning once the DNS record is successfully verified.
Auth0 sets the certificate.status to provisioned when the certificate is successfully created and deployed. The certificate.renews_before attribute indicates the date by which Auth0 automatically renews the certificate.

How is the verification failure resolved for an Atuh0 custom domain?

Auth0 sets the custom domain status to failed if the verification process fails. Review the verification.error_msg attribute to determine how to proceed. The verification.error_msg attribute displays one of the following errors:

DNS verification record issue: Auth0 cannot verify the Canonical Name (CNAME) or Text (TXT) record. This occurs if the record does not exist, is incorrect, or has not propagated yet. Auth0 attempts to verify the DNS record for up to seven days before failing.
- NOTE: This DNS record must remain in place permanently for Auth0 to automatically renew the certificate in the future.
Domain conflicts with network configuration: This typically indicates that Cloudflare is the DNS provider and Zone Hold is enabled. The Zone Hold prevents Auth0 from verifying the custom hostname. Address this error message by performing these steps.
1. Remove the Zone Hold from the DNS zone in Cloudflare.
2. Navigate to Branding and select Custom Domains in the Auth0 Dashboard.
3. Select Verify to restart the process.
4. Re-enable the Cloudflare Zone Hold once verification is successful.
CAA record issue: Auth0 cannot obtain the certificate for the custom domain. This typically occurs because the DNS Certification Authority Authorization (CAA) records of the domain restrict which Certificate Authorities can issue certificates for the domain. Address this error message by removing the CAA records for the exact custom domain undergoing verification. This allows Auth0 to order and provision the certificate without restrictions.
- Determine the current CAA records using a command-line tool like dig.
```
dig <example-custom-domain.com> +short CAA
```

NOTE: Replace example-custom-domain.com with the actual custom domain.

What checks are needed to resolve a custom domain stuck in pending verification?

DNS propagation takes up to 48 hours. Verify the configuration by performing these checks if the error persists in the Dashboard.

Ensure that the CNAME record is properly configured in the domain management service. Confirm the configuration of the CNAME record using a terminal command like dig or a third-party DNS lookup tool (for example, Mxtoolbox or Google Public DNS). Ensure the tool used aligns with organizational guidelines.
Ensure that the domain name is not already associated with an A record.
Ensure that no errors exist in the typed or copied CNAME record domain name or value.
Wait 4 hours before reverifying the domain if the custom domain is still pending verification after completing the previous checks. Do not recreate the custom domain when reverifying to avoid service interruptions.

How does Cloudflare CNAME flattening affect custom domains?

CNAME flattening affects the Auth0 verification and certificate renewal processes due to the way it handles DNS records. Enabling CNAME flattening in Cloudflare after setting up a custom domain does not prevent certificate renewal.

NOTE: Auth0 recommends turning off CNAME flattening unless it is strictly necessary, as outlined in the Understand and configure CNAME flattening documentation. CNAME flattening for Auth0-managed certificates is an unsupported configuration that breaks the custom domain without notice when enabled.

Delegate the subdomain for Auth0 to another DNS provider if CNAME flattening is required for all subdomains managed by Cloudflare, and a specific subdomain must be configured as an Auth0 custom domain. Review the Delegating Subdomains Outside of Cloudflare documentation in Cloudflare for more information. This enables the use of CNAME flattening for all subdomains except the one used for Auth0.

How is the You should not be hitting this endpoint error resolved?

Additional configuration is required if this error occurs during custom domain configuration. The required configurations vary depending on the setup. Review the Configure Features to Use Custom Domains documentation for more information.

How is the Service not found error resolved?

If the application issues an /authorize request with audience=https://<login.acmetest.org>/userinfo, the server returns the error above. This occurs because the API identifier for the /userinfo endpoint remains https://<exampleOriginalAuth0Domain>/userinfo even if a custom domain is set. Using the custom domain in calls to the Auth0 Management API produces the same error.

To resolve this error:

Configuring the application to use audience=https://<exampleOriginalAuth0Domain>/userinfo.
Alternatively, remove the audience=[...]/userinfo parameter entirely if the application is flagged as OIDC-Conformant in the OAuth2 tab of the Advanced Settings for the application.