Troubleshooting

When a custom hostname certificate is stuck in Pending Validation or fails to issue, a domain control validation (DCV) step did not complete successfully.

DCV for SaaS involves two parties with distinct responsibilities. Use the following table to identify who needs to act before troubleshooting a specific error.

The CA error reference specifies who needs to act for each error type.

Before investigating a specific error, verify the following:

• DCV tokens are placed — for TXT validation: your customer has added every TXT record returned in ssl.validation_records to their DNS. For HTTP validation, the method determines who serves the token:
  • Automatic HTTP: Cloudflare serves the token once the custom hostname CNAME (or apex A record) points to your SaaS target. No token placement is required from your customer.
  • Manual HTTP: you serve the DCV token from your origin at the path specified in ssl.validation_records[].http_url, returning the body in ssl.validation_records[].http_body. Refer to HTTP validation for details.
• Tokens are not expired — Let's Encrypt tokens expire after 7 days. Google Trust Services and SSL.com tokens expire after 14 days. If tokens may have expired, refresh them.
• CAA records allow the CA — CAA records are evaluated from the hostname up the DNS tree. The CA first checks the custom hostname itself (for example, shop.example.com), and only moves up to the parent domain (example.com) if the subdomain has no CAA records. A restrictive record at any level that contains CAA records will block issuance. Refer to CAA records for details.
• DNS is reachable — your customer's authoritative DNS must respond without SERVFAIL from all geographic locations.
• No Workers intercepting DCV paths — if your SaaS zone uses a Worker as the fallback origin, ensure it passes through /.well-known/pki-validation/* and /.well-known/acme-challenge/* without modification.

For DCV issues that apply to all Cloudflare zones (WAF rules, redirects, DNS configuration), refer to Troubleshooting DCV.

The following errors appear in ssl.validation_errors on the custom hostname object.

If a custom hostname's ssl.validation_errors contains a CAA-related error, your customer's CAA records are preventing the certificate authority from issuing a certificate for their domain. Your customer needs to resolve this issue.

Ask your customer to check CAA records at both the subdomain and parent domain level, since either may be authoritative:

dig CAA shop.example.com
dig CAA example.com

The records must permit the certificate authority you selected for their custom hostname. Add the appropriate records based on the selected CA:

# Google Trust Services
example.com CAA 0 issue "pki.goog; cansignhttpexchanges=yes"
# Add issuewild only if you need wildcard certificates
example.com CAA 0 issuewild "pki.goog; cansignhttpexchanges=yes"

# Let's Encrypt
example.com CAA 0 issue "letsencrypt.org"
# Add issuewild only if you need wildcard certificates
example.com CAA 0 issuewild "letsencrypt.org"

# SSL.com
example.com CAA 0 issue "ssl.com"
# Add issuewild only if you need wildcard certificates
example.com CAA 0 issuewild "ssl.com"

If your customer does not intend to restrict certificate issuance, they can remove all CAA records. For more details, refer to CAA records FAQ.

DCV tokens become invalid in the following situations:

• The token validity period expires before your customer places them (Let's Encrypt: 7 days; Google Trust Services and SSL.com: 14 days).
• The custom hostname is deleted and re-created.

The custom hostname shows ssl.status: pending_validation and ssl.validation_errors reports a missing token on a domain your customer believes is correctly configured, or your customer confirms they placed the token but validation has not progressed.

To request a DCV recheck, send a configuration-neutral PATCH request to the Edit Custom Hostname endpoint. First retrieve the current hostname with a GET request, then echo ssl.method, ssl.type, and ssl.settings exactly as returned. Omitting or altering any of these fields may reset non-default settings (such as Early Hints or minimum TLS version).

# Step 1: retrieve the current ssl configuration
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{custom_hostname_id}" \
  --header "Authorization: Bearer <API_TOKEN>"

# Step 2: send a PATCH using the ssl object from the GET response.
# ssl.settings must be included as an object if present; omit the field entirely if absent or null.
curl --request PATCH \
  "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{custom_hostname_id}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "ssl": {
      "method": "<method_from_get>",
      "type": "dv",
      "settings": { <ssl_settings_object_from_get> }
    }
  }'

A custom hostname enters Timed Out Validation (ssl.status: validation_timed_out) when DCV did not complete before the retry schedule ended.

To restart the DCV cycle, send a configuration-neutral PATCH request to the Edit Custom Hostname endpoint. Retrieve the current hostname with a GET request first, then echo ssl.method, ssl.type, and ssl.settings exactly as returned.

# Step 1: retrieve the current ssl configuration
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{custom_hostname_id}" \
  --header "Authorization: Bearer <API_TOKEN>"

# Step 2: send a PATCH using the ssl object from the GET response.
# ssl.settings must be included as an object if present; omit the field entirely if absent or null.
curl --request PATCH \
  "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{custom_hostname_id}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "ssl": {
      "method": "<method_from_get>",
      "type": "dv",
      "settings": { <ssl_settings_object_from_get> }
    }
  }'

After sending the PATCH, poll the Custom Hostname Details endpoint and check ssl.validation_records. Only share updated tokens with your customer if the token values have changed. Make sure the tokens are placed before they expire again.

When using SSL.com as the certificate authority, Cloudflare requests both an RSA certificate and an ECDSA certificate. Each certificate type goes through its own DCV cycle and can validate and issue independently. However, the certificate pack is not activated or deployed until both certificates have issued successfully.

Ask your customer to publish every TXT record returned in ssl.validation_records — do not assume the number of records or infer which corresponds to RSA or ECDSA. The field lists all pending authorizations and must be satisfied in full before the certificate pack becomes active.

Cloudflare's CA partners occasionally flag a domain as "high risk" — typically only for domains that Google's Safe Browsing service has flagged for phishing or malware.

If a domain is flagged by the CA, you need to contact Support before validation can finish. The API call will return indicating the failure, along with a link to where the ticket can be filed.

If certificate validation is stuck despite the correct CNAME or TXT records being in place, a conflicting _acme-challenge TXT record may be preventing the certificate authority from completing validation.

Check whether the delegation CNAME is in place at the _acme-challenge hostname:

dig _acme-challenge.example.com CNAME +short

• If this returns nothing, the delegation CNAME is missing. Run a TXT query to check whether a hardcoded record is also present:

  dig _acme-challenge.example.com TXT +short

  If this returns a raw token string, a hardcoded _acme-challenge TXT record is blocking certificate issuance — remove it before adding the delegation CNAME.

• If this returns a CNAME target but certificate validation is still stuck, the conflict is likely a hardcoded _acme-challenge TXT record inside your customer's direct Cloudflare zone. Because resolvers follow the CNAME chain rather than exposing records at the source name, the only way to confirm this is to inspect the customer's zone directly: go to DNS > Records in the Cloudflare dashboard for their zone and look for any _acme-challenge TXT entries.

Record from a prior Cloudflare certificate order — Cloudflare adds _acme-challenge TXT records during certificate issuance. Records from a previous or abandoned order may persist and are not always visible in the Cloudflare dashboard. Contact Cloudflare Support to have them removed.

Record in a direct Cloudflare zone — If your customer's domain is also present in a direct Cloudflare zone (for example, they proxy example.com through their own Cloudflare account), that zone may have an _acme-challenge TXT record from a Universal SSL or Advanced certificate order. When the certificate authority queries _acme-challenge.example.com, it resolves the record from the direct zone rather than following the delegated DCV CNAME.

To resolve this, ask your customer to remove the _acme-challenge TXT record from their zone's DNS settings in the Cloudflare dashboard, then trigger an immediate validation check.

You can send a PATCH request to the Edit Custom Hostname endpoint to request an immediate validation check on any certificate. Retrieve the current hostname with a GET request first and use the current ssl object (including ssl.settings if present) as the PATCH body, not the values from the original creation request.

• Troubleshooting DCV — DCV issues that apply to all Cloudflare zones: WAF rules, redirects, DNS settings, and CA errors
• Token validity periods — how long DCV tokens remain valid per CA
• DCV backoff schedule — how Cloudflare retries DCV before timing out
• Validation status — what each ssl.status value means
• Delegated DCV — let Cloudflare manage DCV on behalf of your customers