Fix a custom domain that is not working

A custom domain that will not verify almost always has one of six causes. This page goes through them in the order they are worth checking, with the command that tells you which one you have.

Availability

Plan: Starter and above.
Where: Domains in the sidebar, then Refresh on the domain card.

Start here

Ask the internet what your domain resolves to, from outside your own network:

dig +short go.example.com CNAME
dig +short example.com A
dig +short _vercel.example.com TXT

A subdomain should answer cname.codeqr.io., a root domain should answer 76.76.21.21, and the TXT record should return the vc-domain-verify=… value shown on the domain card. Anything else is the problem, and the sections below name it.

The Cloudflare proxy is on

The most common cause by a wide margin. If your DNS is on Cloudflare and the record has the orange cloud enabled, Cloudflare answers for your domain with its own addresses. Verification never sees the record you added, and the domain sits on Pending Verification or Invalid Configuration forever.

Fix: open the DNS record in Cloudflare and switch the proxy status to DNS only — the gray cloud. The record value stays the same.

Symptoms that point here even before you check: dig returns two addresses that are not 76.76.21.21, or the site loads with a Cloudflare error page — 526, 525 or 1014. A redirect loop ending in ERR_TOO_MANY_REDIRECTS is the same family, caused by Cloudflare's Flexible SSL mode; Full (strict) is the setting that works with an origin that has its own certificate.

A CAA record is blocking the certificate

The domain resolves correctly, but https:// never starts working. If certificate issuance fails with a message naming CAA — CAA record for example.com prevents issuance — the domain has a CAA record that lists which certificate authorities may issue for it, and the one used here is not on the list.

dig +short example.com CAA

Fix: if the command returns nothing, CAA is not your problem — an absent CAA record allows every authority. If it returns entries, add letsencrypt.org to them. Note that CAA is inherited: a record on example.com also governs go.example.com.

The domain is already in use somewhere else

A domain can be attached to one place at a time on the underlying infrastructure. If it is already connected to another account, verification is refused until ownership moves, which is exactly what the TXT _vercel record does.

Fix: add the TXT record shown on your domain card, at the root of the domain, and select Refresh. If the domain currently serves a live website on the same infrastructure, be deliberate: this transfer takes the domain away from that site.

There is a conflicting record

A hostname cannot hold a CNAME next to an A, AAAA or another CNAME. Providers often accept both silently and then serve the wrong one.

Fix: delete every other record for that exact name, keep the one from Point your domain with a CNAME or A record, and check with dig that only one answer comes back.

You are looking at a cached answer

The record is right, dig from a colleague's machine agrees, and your browser still lands somewhere else. Resolvers hold the previous answer for as long as its TTL said, and your own machine holds it again on top of that.

Fix: wait — the ceiling is the old TTL, not a fixed number of hours. To check without your own cache in the way, query a public resolver:

dig +short go.example.com CNAME @1.1.1.1

The record is right and links still do not open

Two details catch people here:

A trailing dot. Some panels require cname.codeqr.io. and some reject it. Follow the format the other records in your zone already use.
An accented or non-Latin domain. It must be entered in its punycode form (xn--…), which is what your registrar shows in the zone file.

What happens if it stays broken

CodeQR checks configured domains hourly. If a domain stays invalid, everyone in the workspace gets an email after 14 days and another after 28. After 30 days the domain is suspended and flagged for manual review.

Suspension does not delete anything. The domain, its links, its QR codes and their statistics stay in place, and fixing the DNS record clears the state on the next check. The email you receive is more alarming than the behavior — it says the domain will be deleted, which is not what happens.

Verify it works

curl -sSI https://go.example.com/summer

HTTP/2 302
location: https://example.com/menu

If you get a 302 with your destination, the domain is healthy regardless of what any panel says. A 404, a Cloudflare error page or a certificate warning each point back to a section above.

Troubleshooting

The status says Invalid Configuration

DNS answers, but with the wrong value. Compare what dig returns against the record on the domain card. The Cloudflare proxy is the first thing to rule out.

Links on the domain suddenly stopped working

Something changed in DNS: a zone migration, a nameserver change at the registrar, or a record deleted during unrelated maintenance. Re-add the record and select Refresh.

My domain expired at the registrar

Nothing in CodeQR can compensate for that — the domain no longer resolves for anyone. Renew it, and the links resume once DNS is restored. If the domain is gone for good, read Change or remove a domain without losing links before touching anything in the workspace.

Everything checks out and it still will not verify

Select Refresh rather than reloading the page, and give it a few minutes between attempts. Repeated checks in a short window can be rate limited upstream, which shows up as a check that fails for no visible reason.