White Label DNS troubleshooting

Most White Label Lite setups go from CNAME-added to fully-active in under 30 minutes. When they don't, it's almost always one of four things: DNS hasn't propagated yet, a CDN proxy is in the way, a CAA record is blocking Let's Encrypt, or the CNAME points to the wrong target.

This guide covers each case in the order you should rule them out, plus a few rarer failure modes.

How to check DNS without a terminal

Before troubleshooting anything else, confirm whether your CNAME is actually live globally. The dashboard's status pill is one signal, but a real DNS propagation map gives you a much clearer picture.

Open whatsmydns.net or dnschecker.org:

1. Enter your subdomain (for example app.yourbrand.com).
2. Pick CNAME from the dropdown.
3. Look at the world map.

If you see trekmail.net showing up at most of the green-check locations, your DNS is fine and the issue is somewhere else (cert provisioning, CAA, proxying). If you see your old record, or no record at all, DNS hasn't applied yet — wait 10-30 minutes and retry.

If you're comfortable in a terminal, dig CNAME app.yourbrand.com from your shell tells you the same thing. Look for trekmail.net in the ANSWER section.

Status says "pending DNS" longer than 30 minutes

DNS gets re-checked the moment you save the settings page, and a weekly health sweep catches anything that didn't pick up the first time. If status hasn't moved after an hour, click Force re-provision on the settings page to retry immediately. Common causes when it really is stuck:

Your DNS provider is slow to propagate. Some cheaper registrars take up to an hour. Cloudflare and Route 53 are typically under 5 minutes. If you used a less-known registrar, give it the full 60-90 minutes before assuming something is wrong.

Your CNAME points to the wrong target. It must point exactly to trekmail.net. Not trekmail.com (we own that too but it's not the WL endpoint). Not your old branded domain. Not a load-balancer URL. Just trekmail.net. Open the settings at your DNS provider and confirm the Value/Target field.

You added an A record instead of a CNAME. Some registrars default to A records when you type a hostname. The dashboard requires CNAME — A records won't work. Delete the A record and add a CNAME pointing to trekmail.net.

The subdomain hostname is wrong at your provider. If your domain is mybrand.com and you want app.mybrand.com, the Host/Name field at your DNS provider should be app, not app.mybrand.com. Some providers want the full hostname, others want just the subdomain prefix — check your provider's docs.

The apex domain is on a different DNS provider than the subdomain. This is rare but happens when an old vendor is still pointed at by your registrar's NS records. Make sure the DNS provider editing the zone is actually the one your domain is delegated to. You can confirm with dig NS yourbrand.com (or use whatsmydns.net with NS in the dropdown).

Cloudflare orange-cloud breaks SSL provisioning

If you use Cloudflare as your DNS provider, you'll see a small cloud icon next to each record. Orange means proxied — Cloudflare sits in front of the request, terminating SSL on their side. This breaks our Let's Encrypt issuance because LE's challenge can't see our real server.

Fix: click the orange cloud next to your app CNAME and turn it grey (DNS-only mode). Save. Within a few minutes the next DNS re-check picks up the change and SSL provisioning succeeds.

You can still use Cloudflare for the apex domain (yourbrand.com) with orange-cloud proxying — only the WL Lite CNAME needs to be DNS-only. The same caveat applies to other CDN/proxy services: Fastly's wildcard rules, Sucuri proxying, Akamai, etc.

Status says "cert failed — blocked CAA"

A CAA record is a DNS setting that tells the world which certificate authorities are allowed to issue SSL certificates for your domain. If your domain has a CAA record that doesn't include Let's Encrypt, our cert issuance fails before LE even sees the request.

You can check if you have a CAA record with:

• whatsmydns.net (pick CAA from the dropdown)
• dig CAA yourbrand.com in a terminal

Fix: add a CAA record at your apex domain that permits Let's Encrypt:

yourbrand.com. IN CAA 0 issue "letsencrypt.org"

The 0 is the flags byte (almost always 0 for normal use). issue is the property. "letsencrypt.org" is the CA you're authorizing.

Existing CAA records can stay alongside this one — CAA entries are additive, not exclusive. If you have an existing 0 issue "digicert.com" record for some other service, leave it; just add the Let's Encrypt one too.

If you don't have any CAA records at all, you don't need to add one — the absence of CAA is interpreted as "any CA is allowed." The fix above only applies if you have at least one CAA record that excludes Let's Encrypt.

Status says "cert failed — generic"

A generic cert-failure status usually means one of:

• Let's Encrypt rate limit. LE limits issuance to 50 new certificates per registered domain per week. If you've been retrying repeatedly during testing, you may have hit it. Wait an hour and retry, or longer if your apex has many subdomains being issued certificates simultaneously.
• Transient network failure. LE's API or our bastion had a brief connectivity hiccup. Click Force re-provision on the Settings page to retry.
• Your DNS regressed. Your CNAME was fine when we started, but propagation reverted or the record was removed. Confirm via whatsmydns.net.

If a force-reprovision doesn't fix it within an hour, contact support. Include your custom domain name in the ticket and we can check our LE-issuance logs.

Domain was active, now status changed

Once your domain hits active, we keep it that way as long as DNS and the certificate are healthy. If status changes back:

• "DNS broken" — the CNAME at your provider was removed or pointed somewhere else. Restore the CNAME pointing to trekmail.net and the next DNS check restores active status (within 10 minutes).
• "Cert near expiry" — Let's Encrypt certs are 90 days. We auto-renew before expiry; if renewal fails, you'll see this status as a warning. Force-reprovision usually resolves it.
• "Suspended" — administrator action. Only an internal operator can suspend a brand profile (typically for ToS or abuse issues). Contact support.

Common scenarios

"I changed my CNAME a few hours ago and status is still pending." DNS caches at intermediate resolvers can hold an old record for up to an hour. Wait, retry. Also confirm the CNAME is published at the authoritative server (whatsmydns.net world map should show consistent green checks).

"I deleted the old CNAME at my old provider but the new one isn't picking up." Some providers don't update authoritative records when you delete from the panel — they wait for an internal sync. If you switched DNS providers entirely, check that your registrar's NS records point to the new provider (dig NS yourbrand.com).

"My apex yourbrand.com is set up with proxying, can I use it for the WL subdomain too?" Yes, but only if the WL subdomain CNAME is set to DNS-only (grey cloud in Cloudflare). The apex can stay proxied.

"Can I use a wildcard CNAME (*.mybrand.com → trekmail.net)?" No. We require a specific subdomain to bind the SSL certificate to. Wildcards complicate Let's Encrypt issuance and aren't supported.

"I want to move my domain to a new subdomain." Edit the custom domain on the settings page, then update your CNAME accordingly. The old subdomain stops serving after DNS catches up — the new one comes online after SSL re-issues. Allow 10-30 minutes for the swap.

"My ISP / DNS resolver doesn't seem to see the new record." Try resolving from a different network (your phone on cellular, a public DNS resolver like 1.1.1.1, or dig @1.1.1.1 CNAME app.yourbrand.com). If a public resolver sees the new record but your ISP doesn't, the issue is with their cache — wait for their TTL to expire.

What's next

• Set up White Label Lite — the original setup steps if you're partway through.
• White Label Lite pricing FAQ — billing-related questions.
• Canceling White Label Lite — what happens to your domain if you cancel.
• Recommended DNS records — the broader picture of DNS records TrekMail uses.

If you're still stuck after working through this guide, open a support ticket with your custom domain in the body — we can read our LE-issuance logs and tell you exactly what's failing.