Troubleshoot a failed domain

When a custom domain doesn’t reach Active status, the cause is nearly always something with the DNS records or how they’re being served. This article walks through the diagnostic flow.

Before you start

• Open Settings → Custom Domains in a tab. The status of your domain row is the starting point for the diagnosis.
• A terminal with dig or a web-based DNS lookup tool (whatsmydns.net, dnschecker.org, etc.) for checking actual DNS resolution.

Step 1 — Read the current status

Each domain row shows one of these states:

• Awaiting DNS — Atender is polling for the records you were given. They haven’t resolved to the expected values yet — either because DNS is still propagating, or because the records weren’t added correctly.
• Issuing certificate — DNS resolved. The TLS certificate is being issued by the provider. This usually takes a few minutes; if it sits here for more than 30, something’s wrong at the certificate-provider end.
• Failed — The certificate provider gave up after retrying — usually because the DCV records can’t be verified. Hover the status badge or open the row for the failure detail.
• Disabled — An admin disabled the domain manually. Re-enable from the row’s menu if you want it serving again.

Your fix path depends on which state the domain is stuck in.

Step 2 — Stuck on “Awaiting DNS”

This means the records you added aren’t visible to Atender yet, or they don’t match what was requested.

Check that the records exist publicly. From a terminal:

dig A help.example.com
dig TXT _acme-challenge.example.com

Use the actual hostname and record names that Atender showed you. The output should show your record values. If it shows nothing or shows old values, your DNS provider hasn’t pushed the change out yet.

Check that the values match exactly. Common mistakes:

• Trailing dots. Some DNS panels add a trailing . to record names (help.example.com.); others don’t. Both are valid — but if you copied a name with a trailing dot into a panel that doesn’t expect it, the panel might create help.example.com..example.com (the full origin gets appended again). Look for duplicate domain segments in the resulting record.
• Quoted TXT values. Some panels require TXT values wrapped in quotes ("value"); others auto-quote them. If you double-quoted, the actual TXT record value contains the quotes. Remove them.
• Wrong record TYPE. If Atender asked for an A record and you added a CNAME (or vice versa), DNS lookups won’t return what’s expected.

Force a fresh check. Once you’ve fixed the record, click Re-check DNS on the domain row in Atender. This bypasses the normal poll cycle. It’s rate-limited to about every 30 seconds — if it doesn’t respond immediately, try again shortly.

Wait for propagation. Some DNS providers and TTL configurations propagate in a minute or two; others take an hour. If you set a 24-hour TTL on a record you later replaced, the old value will be cached at resolvers for up to 24 hours. While testing, keep TTLs short (300–600 seconds).

Step 3 — Stuck on “Issuing certificate”

DNS resolved correctly, but the TLS certificate provider is having trouble.

Cloudflare proxy is on. This is the most common cause by a wide margin. If your records are at Cloudflare and the proxy status is Proxied (orange cloud), the certificate provider can’t reach Atender’s edge to complete the HTTP challenge or read the DCV records cleanly. Switch every record at this hostname to DNS only (gray cloud). Then click Re-check DNS in Atender.

DCV records were removed too early. The DCV records (TXT or CNAME, typically with names like _acme-challenge.<your-host>) need to stay in place until the certificate finishes issuing — and usually for the lifetime of the domain, so renewals work too. If you cleaned them up after seeing DNS succeed, add them back.

Time. First-time certificate issuance can take longer than the optimistic “a few minutes.” Wait 10–15 minutes. If it’s still in Issuing certificate after that, move on to the Failed-state advice below.

Step 4 — Stuck on “Failed”

The certificate provider exhausted its retries.

Open the row for the verification errors. Atender stores the last batch of errors from the certificate provider on the domain record. They’ll often name the specific record that couldn’t be verified — e.g. “TXT record at _acme-challenge.help.example.com does not match expected value.”

Recreate the missing record correctly. Fix the named record, then click Re-check DNS to force a retry.

Recreate the domain entry as a last resort. If the verification errors don’t make sense and you’ve confirmed every record is correct, delete the domain entry in Atender and add it again. This gets you a fresh set of DCV records and resets the retry counter. (The records may be different the second time — that’s expected.)

Step 5 — Active, but loading the wrong content

Domain is Active but serving the wrong tenant’s content, or showing a “tenant not found” page.

Confirm the product is set correctly. Each domain entry is bound to either Knowledge Base or Status page. If you mixed them up, the domain serves the wrong surface. Delete the entry and re-add with the right product.

Confirm the hostname matches. Check the hostname in the Atender row character-for-character against what you typed in your browser. Trailing or leading whitespace at creation time can produce a row that doesn’t match what’s in DNS.

Provider-specific gotchas

• Cloudflare — Proxy mode (orange cloud) breaks TLS. Switch every record to DNS only.
• Route 53 — Alias mode for the A record can mis-route. Use a plain A record with the IP value Atender provided.
• GoDaddy / cPanel — Some panels auto-append the domain to the Name field. If you enter help.example.com as the name and it appears as help.example.com.example.com, just enter help instead.
• NS1 / dnsimple / Namecheap — TTL defaults vary widely. Stick to 300–600 seconds while setting up.

See also

• What are Custom Domains?
• Add a custom domain