← Back to blog

CNAME Lookup: How to Check a CNAME Record and Read the Result

Domainee·
cname lookupcheck cname recordscname checkcname checker
CNAME Lookup: How to Check a CNAME Record and Read the Result

A CNAME lookup asks DNS which name a hostname is an alias for, then follows that chain through to the A record behind it. If the answer is the target you were told to use, the record is right. If it's empty or points somewhere else, it isn't.

You can run one three ways, right now:

  • In the browser: the free CNAME lookup and generator. No signup.
  • With one curl call against the free API (below).
  • With any DNS tool you already use, like dig.

The curl version:

curl -s "https://api.domainee.dev/v1/tools/cname-lookup?host=www.example.com" | jq

The endpoint is keyless and CORS-enabled. Limits are 30 requests/min and 500 requests/day per IP. There is no uptime commitment, so it fits scripts and audits, not a production dependency. Full details are in the CNAME lookup API reference.

What a CNAME record is (in two sentences)

A CNAME record says "this hostname is an alias for another hostname." The resolver looks up the alias, gets pointed at the canonical name, and follows it to an A or AAAA record.

That's the theory. You came to check something, so on to the result.

How to read the result

A correct result for a custom domain

Say your customer added app.acme.com and you told them to point it at your SaaS. A correct lookup shows app.acme.com as an alias for the target you gave them.

For a Domainee custom domain, that target is edge.domainee.dev. The record shows the Domainee name. It is not hidden. DNS records are public, and a lookup will show it.

The dig-style version, with illustrative output below it:

dig +short CNAME app.acme.com
edge.domainee.dev.

The chain

A CNAME can point at another CNAME before it lands on A records. The lookup tool follows the chain through to the A record behind it, so you see every hop, not just the first.

The chain is how you spot an alias that points somewhere you didn't expect. One hop too many, or the wrong name at the end, is usually the whole story.

The empty result

Nothing returned means there is no CNAME at that exact name. The usual reasons:

  • The record isn't added. It happens on a Tuesday afternoon more often than you'd think.
  • It's on the wrong host. www versus the apex, or an extra suffix like app.acme.com.acme.com, because the DNS provider appended the domain to a name that was already fully qualified.
  • It hasn't propagated yet. Resolvers may still hold the old answer until its TTL runs out.

To see whether a change has rolled out, use the DNS propagation checker. It shows which resolvers still hold the old answer.

On TTL: keep CNAME TTLs low, 300 to 3600 seconds, for SaaS-hosted records so changes propagate fast.

Why your CNAME check fails: the common causes

A failed CNAME check usually comes down to one of five things. Here they are, with the Domainee monitor state each one maps to.

CauseWhat you seeDomainee monitor state
Wrong target or typoThe CNAME exists but points elsewheredns_incorrect
Nothing resolving yetEmpty lookupdns_not_resolving
CNAME at the apexBreaks other records on the rootCheck the root's other records
Conflicting records at the same nameAnother record sits on the hostCheck the host's other records
CAA blocks Let's EncryptCNAME is right, SSL still failsPreflight warns

Wrong target or typo

One character off in edge.domainee.dev and the lookup resolves to nothing useful. That's dns_incorrect: DNS answers, just not with the target you need. Compare the lookup result to the target character by character.

Nothing resolving yet

No record, wrong host, or still propagating. That's dns_not_resolving. Wait out the TTL, then check again.

CNAME at the apex

This is the big one. A name that has a CNAME can't have any other record on it. Put a CNAME at acme.com and it overrides the MX records, which breaks email.

Read why a CNAME at the root is impossible for the full story. Before you touch a root domain, run the MX lookup and see what's on it.

Some DNS providers offer CNAME flattening at the apex. Cloudflare, Route 53 (as an Alias) and Namecheap do. GoDaddy does not. Where an apex provider disallows CNAME, we offer two anycast A records instead.

Conflicting records at the same name

Same rule, different symptom. If app.acme.com already has a TXT or A record, adding a CNAME there is a conflict. Check what else lives on the host before you blame propagation.

CAA records that block Let's Encrypt

The CNAME can be perfect and SSL can still fail. A CAA record that doesn't allow Let's Encrypt stops certificate issuance. Domainee's preflight warns on CAA records that block Let's Encrypt, so you hear about it before the 2am cert failure.

A correct CNAME is one of three layers: DNS, HTTP routing and TLS. Each fails differently. DNS being right tells you nothing about the other two.

Checking CNAMEs for a SaaS's customers

This section is for product teams. If your users bring their own domains, you can't ask them to run dig. You need the CNAME checked for them, repeatedly.

Create the domain with one call:

curl -X POST https://api.domainee.dev/v1/domains \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"hostname":"app.acme.com","originUrl":"https://your-origin.example.com"}'

The call returns the CNAME your customer adds. status and monitorStatus report the DNS state from there. Your customer never needs a registrar account. One CNAME is the whole ask.

Each domain is re-checked every 5 minutes, or on demand via POST /v1/domains/{id}/check.

The monitor states, in plain terms:

  • unknown: no verdict yet.
  • dns_not_resolving: nothing is resolving at the hostname yet.
  • dns_incorrect: DNS answers, but with the wrong target.
  • pending_ssl: DNS is fine, the certificate is on its way.
  • active_ssl: working. Let's Encrypt SSL is issued on first request and renewed automatically.
  • ssl_failed: certificate issuance failed.
  • ssl_expired: the certificate expired.

A generic "add a CNAME" note works for some customers and baffles the rest. GET /v1/domains/{id}/instructions detects the DNS provider from public NS records and returns provider-specific steps. The free generator also gives copy-ready instructions for Cloudflare, GoDaddy and Route 53.

Lookup vs generator: building the record you need

The free tool has two modes. Lookup verifies an existing CNAME. Generator builds the record your DNS provider expects, with copy-ready instructions for Cloudflare, GoDaddy, Route 53 and more.

  1. Pick lookup or generator.
  2. Enter the hostname.
  3. Copy the record, or verify the one you added.

Generate it, add it at your provider, then flip to lookup to confirm. No signup.

FAQ

What is a CNAME lookup?

A CNAME lookup asks DNS which hostname another hostname is an alias for. A good tool also follows the chain through to the A record behind it. It's the quickest way to confirm a custom domain points where it should.

How do I check a CNAME record?

Enter the hostname in the free CNAME lookup and generator, or run dig +short CNAME your.hostname. Compare the result to the target you were given. If they match, the DNS layer is done.

How do I check a CNAME record from the command line or API?

Use dig +short CNAME host, or the free keyless API: curl -s "https://api.domainee.dev/v1/tools/cname-lookup?host=www.example.com" | jq. The limits are 30 requests/min and 500 requests/day per IP.

Why does my CNAME lookup return nothing?

There's no CNAME at that exact name. The record may not be added, may be on the wrong host (www versus apex, or a doubled suffix), or may not have propagated. Check the exact hostname first, then the DNS propagation checker.

Can I put a CNAME at my root (apex) domain?

Not as a plain CNAME, because it would override the other records on the root, including MX. Some DNS providers offer CNAME flattening. Where a provider disallows CNAME at the apex, Domainee offers two anycast A records.

Can a CNAME coexist with MX or other records?

No. If a name has a CNAME, it can have no other records. That's why a CNAME at acme.com breaks email.

How long does a CNAME change take to show up?

It depends on the TTL of the old record and on resolver caching. Low TTLs mean faster changes, which is why we suggest 300 to 3600 seconds for SaaS-hosted records. The propagation checker shows which resolvers still hold the old answer.

What TTL should I use for a CNAME?

Keep it between 300 and 3600 seconds for SaaS-hosted records. Low values let you fix a typo without waiting out a long cache.

What does a CNAME chain look like in the result?

The hostname points to a name, which may point to another name, and the chain ends at A records. The lookup tool follows it all the way through to the A record. For a Domainee custom domain, the target you should see is edge.domainee.dev.

Why does my custom domain still fail SSL when the CNAME is correct?

DNS is only one of three layers. A CAA record that blocks Let's Encrypt will stop issuance even with a perfect CNAME, and Domainee's preflight warns on those. The monitor also reports pending_ssl, ssl_failed and ssl_expired so you can see which stage you're at.

Check it now

Run your hostname through the free CNAME lookup and generator. Prefer scripts? The CNAME lookup API reference has the endpoint.

Building custom domains into a SaaS? Create your first domain on the free tier: 20 domains and 100 GB/month, free forever. A card is required before the first domain and is charged $0 under the free tier. We monitor the CNAME every 5 minutes. You get the API.

CNAME Lookup: Check a CNAME Record and Read the Result | Domainee