DNS and TLS

A RouteSeam domain goes live through three gates: DNS verification, TLS provisioning, then Active. This page explains what happens at each gate and how to recover from the two failure states. For the record values themselves, see DNS setup.

Verifying DNS

After you add a domain, RouteSeam shows you exactly one record to create — an A record for apex domains or a CNAME for subdomains — and the domain enters DNS Pending.

Verification runs two ways:

• Check DNS button. Click it on the domain page to run a verification immediately after you save the record at your DNS provider.
• Automatic re-checks. RouteSeam re-checks your DNS periodically in the background, so you do not need to keep pressing the button. When the record resolves correctly, the domain moves to DNS Verified on its own.

A check passes when the hostname resolves to RouteSeam’s edge. Once it does, the domain advances to TLS Provisioning.

How auto-TLS works

HTTPS is mandatory — RouteSeam never serves HTTP-only forwarding. Once DNS verifies, the edge’s Caddy server obtains a certificate from Let’s Encrypt using on-demand TLS:

1. The first HTTPS request for your hostname reaches the edge.
2. Caddy asks RouteSeam’s control plane whether this hostname is allowed to get a certificate. Only domains you have added and verified pass this check, which prevents strangers from minting certificates through RouteSeam’s infrastructure.
3. Caddy completes the ACME challenge with Let’s Encrypt, issues the certificate, and serves the response.
4. The domain is marked Active.

The first request can take a few seconds while issuance completes; subsequent requests use the cached certificate. Renewal is automatic — you never touch certificates.

Fixing dns_failed

A domain enters DNS Failed when verification keeps finding the wrong answer. The usual causes:

Record missing or wrong. Confirm the record exists and matches the value on the domain page:

dig A oldcompany.com +short

For a subdomain pointed by CNAME:

dig CNAME legacy.company.com +short

Propagation delay. DNS changes can take minutes to hours to reach every resolver, and a stale cached answer can make RouteSeam’s check fail even after you fixed the record. Check what public resolvers see:

dig A oldcompany.com @1.1.1.1 +short
dig A oldcompany.com @8.8.8.8 +short

If resolvers disagree, wait and let the automatic re-checks catch up.

Conflicting AAAA or CNAME records. RouteSeam’s verification inspects A, AAAA, and CNAME answers. An AAAA record pointing elsewhere, or a CNAME at a name that also has other records, can win over your A record depending on the client. List everything at the name:

dig ANY oldcompany.com +noall +answer

Remove the stale AAAA or CNAME record, then click Check DNS.

Fixing tls_failed

A domain enters TLS Failed when certificate issuance fails after DNS verified. Common causes:

Let’s Encrypt rate limits. Repeated failed issuance attempts can trip Let’s Encrypt’s per-domain rate limits. Fix the underlying cause first, then use the retry action on the domain page rather than triggering many attempts in a row.

CAA records blocking issuance. A CAA record on your domain controls which certificate authorities may issue for it. If it does not name Let’s Encrypt, issuance is refused. Check:

dig CAA oldcompany.com +short

If records exist and none mention letsencrypt.org, add one:

oldcompany.com.  CAA  0 issue "letsencrypt.org"

Redirect loops and conflicts. If the hostname partially resolves elsewhere, or another service on the domain interferes with the ACME challenge, issuance fails. Make sure the record points only at RouteSeam, then retry TLS from the domain page.

Caution

Do not delete and re-add the domain to escape a failure state. Fix the record or CAA policy, then use Check DNS or the TLS retry — the domain resumes from where it stopped.

Related pages

• Domain lifecycle — every state a domain can be in.
• Redirect types — what happens once traffic arrives.
• Analytics — watching the traffic after go-live.