Skip to main content
Contentstack MCP profile hub is in general availability!

Custom domain stuck on Pending validation in Launch

•
10 min read

You added a custom domain to a Launch environment, copied the records into your DNS provider, and both Domain Status and Certificate Status stay on Pending. Hours later they still do. Or the domain went Active, you switched traffic, and the browser shows a certificate warning.

In almost every case the cause is in DNS: a record of the wrong type, a name your provider rewrote, a CAA record that blocks the certificate authority, or a proxy that sits between visitors and Launch. This guide goes through each one, with a dig command to prove it. It's for anyone moving a site to Launch, especially a live site where downtime isn't an option.

What you'll learn

  • Which three DNS records Launch needs and in what order to add them

  • Why the certificate record must be a CNAME, not a TXT

  • How CAA records, apex domains and multi-level subdomains block validation

  • What to do when Cloudflare or another proxy sits in front of Launch

  • How to redirect between apex and www without losing the query string

Symptoms

  • Domain Status or Certificate Status shows Pending in Settings > Environments > Domains and doesn't change.

  • A status shows Error. Hovering it shows a message and an error code.

  • The apex domain loads, but www doesn't, or the other way around.

  • The domain is Active, but browsers report a certificate for a different name.

  • Visitors see a Cloudflare error page, such as Error 1000 or Error 1014, after you point a proxy at Launch.

  • A redirect from the apex to www drops the utm_ parameters from campaign links.

Hover the Pending or Error status and copy the message. It often names the problem directly, for example a CAA record or a missing validation record.

Why it happens

Launch concept: a custom domain needs three DNS records, added in two steps. Launch shows all of them in the domain's Edit modal.

Record

Type

Purpose

When to add it

Hostname validation

TXT

Proves you own the domain

First

Certificate validation (DCV)

CNAME

Lets the certificate authority issue an SSL certificate

First

DNS record

CNAME for a subdomain, A for an apex

Routes visitors to Launch

After both statuses are Active

With automatic SSL, Launch issues and renews the certificate through an ACME certificate authority such as Let's Encrypt. That authority checks the DCV record before it issues anything. Without that record in the right shape, the certificate waits forever.

The order matters for live sites. If you add the TXT and DCV records while the old host still serves traffic, Launch validates the domain and issues the certificate in the background. When you then switch the CNAME or A record, the certificate is already there, and nobody sees a warning.

DiagramMermaid

Fix it

Start by checking what DNS actually returns. Your provider's dashboard shows what you typed, and dig shows what the world sees. The causes below are ordered from most to least common.

The DCV record was added as a TXT

The hostname validation record is a TXT, so it is natural to add the second record as a TXT too. The certificate validation record is a CNAME. As a TXT it does nothing, and the certificate stays on Pending.

Check both records, using the exact names from the Launch UI:

dig TXT _cf-custom-hostname.www.example.com +short
dig CNAME _acme-challenge.www.example.com +short

The names above are examples. Copy the Name and Value that Launch shows for your domain rather than assuming them. The CNAME lookup must return the value from the Certificate Validation Record section. If it returns nothing and a dig TXT on the same name returns that value, delete the TXT and create a CNAME.

Then open the domain's Actions menu in Launch and choose Revalidate. Use Refresh at the top of the list if the status doesn't update.

Your DNS provider changed the record name

Many DNS providers append the zone to every name you enter. If you type _acme-challenge.www.example.com into the example.com zone, the record becomes _acme-challenge.www.example.com.example.com. Validation looks at the right name and finds nothing.

Check with the doubled name:

dig CNAME _acme-challenge.www.example.com.example.com +short

If that returns your value, rename the record to _acme-challenge.www, without the zone.

Multi-level subdomains follow the same rule. For shop.eu.example.com in the example.com zone, the routing record name is shop.eu and the DCV name is _acme-challenge.shop.eu. If eu.example.com is delegated to its own zone, for example at a different provider, add the records in that zone instead. A record added to the parent zone is never seen once a subzone is delegated.

A CAA record blocks the certificate authority

A CAA record lists which certificate authorities may issue certificates for a domain. Authorities check it before issuing, and they walk up the tree: a CAA record on example.com also applies to www.example.com and shop.eu.example.com.

If your security team set CAA to allow only your current CA, the certificate for Launch can't be issued. The status hover usually mentions CAA when this happens.

dig CAA www.example.com +short
dig CAA example.com +short

If either returns entries and none of them is the authority Launch uses, add one next to the existing entries. Don't remove the others, or you'll break certificates elsewhere. For Let's Encrypt:

example.com.  3600  IN  CAA  0 issue "letsencrypt.org"

Confirm the authority with the message in the status hover, then revalidate the domain. If you upload a custom certificate instead of using automatic SSL, no DCV record is needed, and CAA only has to allow the authority that issued your certificate.

The apex domain is set up like a subdomain

An apex domain, such as example.com, can't have a CNAME in standard DNS. Launch gives you an A record for the apex instead. Copy the IP address from the DNS Record section of the Edit modal, and remove any old A or AAAA records for the apex that still point at your previous host. A leftover record sends some visitors to the old server.

Two more things trip people up:

  • www is a separate domain. Launch only serves hostnames you added to the environment. If example.com works and www.example.com doesn't, add www too, with its own records.

  • Redirect options create domains. When you add an apex with Add www.apex.com (subdomain) and redirect apex domain to it, Launch creates two domains. Each needs its own TXT and DCV records before it goes Active.

If you hit an error while adding a domain, check your plan's domain limit. The number of custom domains per environment and per project depends on your plan, redirect domains included. Contact Contentstack Support to raise it.

A proxy or CDN sits in front of Launch

Launch runs on Cloudflare and includes its own CDN, WAF and DDoS protection. Putting another proxy in front is not recommended, but when you do, it changes how validation and routing work.

Your DNS is in a Cloudflare zone. If the record to Launch is proxied (orange cloud), traffic flows from your Cloudflare zone into Launch's. That needs Cloudflare Orange-to-Orange (O2O):

  1. Create a CNAME for your custom domain that points to the value Launch gives you.

  2. Keep it proxied.

  3. Ask your Cloudflare account team to enable Orange-to-Orange.

Without O2O, visitors get Cloudflare errors such as 1014 instead of your site. If you don't need your own Cloudflare features on this hostname, set the record to DNS only (grey cloud) instead.

Another proxy, such as a WAF or a different CDN. Cloudflare Error 1000 ("DNS points to prohibited IP") usually means the proxy forwards to the default *.contentstackapps.com domain, which resolves to Cloudflare addresses. Fix it like this:

  • Add the public hostname as a custom domain in Launch and validate it with the TXT and DCV records.

  • Point the proxy's origin at the CNAME target Launch shows for that domain.

  • Forward the Host header for that custom domain. Launch routes to the right environment by host.

  • Turn caching off on the proxy. Launch purges its own CDN on every deployment, and can't purge yours. See I published, but my site still shows old content.

Firewall rules and DDoS protection then live on your proxy, because traffic reaches Launch through it.

The redirect drops the query string or goes the wrong way

The apex redirect options in Launch go from the apex to a subdomain, or to another domain in the same environment, with a 301, 302, 307 or 308. Test what your redirect does with a real campaign URL:

curl -sI "https://example.com/pricing?utm_source=newsletter" | grep -i -E "^HTTP|^location"

The location header should keep the path and the query string. If it doesn't, or you need the opposite direction, such as www to the apex, add both domains to the environment without a UI redirect and handle the redirect in an edge function:

// functions/[proxy].edge.js
export default function handler(request, context) {
  const url = new URL(request.url);

  if (url.hostname === 'www.example.com') {
    url.hostname = 'example.com';
    return Response.redirect(url.toString(), 308);
  }

  return fetch(request);
}

Changing hostname on a URL keeps the path and every query parameter. Redirect sources in launch.json can't match a hostname, which is why this belongs in an edge function. Edge functions in practice covers routing by hostname in more depth.

Check that it worked

  1. Both Domain Status and Certificate Status show Active in Launch.

  2. The routing record resolves to the value Launch gave you:

dig www.example.com +short
dig A example.com +short
  1. The certificate covers the hostname:

curl -svI https://www.example.com 2>&1 | grep -i -E "subject:|issuer:|^< HTTP"
  1. Every hostname you serve answers with your site, and every redirect keeps the path and query string.

DNS changes can take up to 48 hours to reach everyone, depending on your provider and TTLs. If dig against a public resolver such as dig @1.1.1.1 returns the right values and Launch still shows Pending, use Revalidate.

Prevent it

  • Add the TXT and DCV records days before go-live, so the certificate exists before you switch traffic.

  • Lower the TTL on the records you will change at cutover a day ahead, and raise it again afterwards.

  • Keep a CAA entry for the authority Launch uses, and tell your security team why it's there.

  • Add every hostname you serve, including www, as its own custom domain.

  • Avoid a proxy in front of Launch. If you need one, use O2O for Cloudflare zones and forward the Host header for anything else.

  • Copy record names and values from the Launch UI every time. They differ per domain.

Key takeaways

  • A custom domain needs a TXT for ownership, a CNAME for the certificate, and then a CNAME or A record for traffic.

  • The DCV record is a CNAME. As a TXT, the certificate never leaves Pending.

  • Check what DNS returns with dig, including doubled names like _acme-challenge.www.example.com.example.com.

  • CAA records on a parent domain apply to every subdomain. Add the Launch authority without removing your others.

  • Cloudflare in front of Launch needs Orange-to-Orange. Other proxies need the custom domain as origin and the right Host header.

  • Use an edge function for www to apex redirects and anything that must keep the full query string.

Next steps

Frequently asked questions

  • Should the certificate validation record be a TXT or a CNAME?

    A CNAME. The hostname validation record is a TXT, but the certificate validation (DCV) record is a CNAME. Adding the DCV record as a TXT leaves the certificate on Pending.

  • How long does custom domain validation take?

    Once the records resolve, Launch validates the domain and issues the certificate on its own. DNS changes can take up to 48 hours to propagate, depending on your provider and TTLs.

  • Do I point my domain at Launch before validation?

    No. Add the TXT and DCV records first and wait until the domain and certificate are Active. Then add the CNAME or A record that routes traffic, so the certificate is ready at cutover.

  • Why does a CAA record block my certificate?

    A CAA record lists the certificate authorities allowed to issue for a domain. If yours doesn't include the authority Launch uses, the certificate can't be issued. Add that authority next to your existing entries.

  • Can I put Cloudflare in front of Launch?

    It is not recommended. If your DNS lives in a Cloudflare zone and you proxy the record, Cloudflare Orange-to-Orange has to be set up. Other proxies must forward the Host header and should not cache.