Dashboard

Domains and HTTPS

DNS troubleshooting

What each step of a domain check reports, word for word, and how to fix the DNS problems it finds.

Use this page when a custom domain stays on "DNS setup required" or "Needs attention". It goes through the steps under Progress on the domain's card, with the messages each step shows and what to change.

Every check runs the same steps in order: "DNS record", "Name servers", "Connection to your app", "Security certificate" and "HTTPS". A step that didn't run because an earlier one hasn't passed shows its name only, greyed out, so fix the first step that isn't done.

Look up your DNS

To see what public DNS returns for your domain, run these on macOS or Linux:

bash
dig +short CNAME app.example.com
dig +short NS example.com

The first command should print connect.hcode.site. (or the name of your own that leads there). The second lists your domain's name servers; these are the servers the "Name servers" step asks.

DNS record

This step looks up the record for your hostname.

Message What to do
"Your domain's DNS points to us." Nothing.
"Your domain reaches us through something in front of it (a CDN, a proxy, or your DNS provider's proxied setting)." Nothing for DNS. The certificate then comes from that service, see HTTPS certificates.
"Your domain's DNS doesn't point to us yet. Add the DNS record shown for this domain; we'll check again automatically." Add the CNAME record shown on the card, or wait for a change you made to spread.
"Your domain's DNS no longer points to us. Put back the DNS record shown for this domain; we'll check again automatically." The domain worked before and the record has changed. Put the CNAME back. HCode keeps the domain connected meanwhile.
"We checked your domain's DNS less than a minute ago, ..." HCode checks a hostname at most once every 30 seconds. Wait a minute and use Check now again.
"We're still checking your domain's DNS. We'll keep checking in the background; check again in a few minutes." The lookup took too long this time. Nothing to change; check again later.

Custom domains shows the record to create. Things that commonly stop this step:

  • The name has your domain twice. Many providers add your domain to the name for you, so typing app.example.com creates app.example.com.example.com. Enter only app.
  • The value has a typo. Copy it with Copy value.
  • There is an A record instead of the CNAME. Custom domains on HCode are pointed with the CNAME only. Delete the A record and add the CNAME.
  • The change hasn't spread yet. Wait, then use Check now.

For a root domain like example.co.za this step says it is a root domain and tells you to use www instead. See Root domains.

Name servers

The first time a domain passes the DNS record step, HCode also asks each of your domain's name servers directly. Every one that answers must have the new record before HCode connects the domain and asks for a certificate, so the certificate request isn't answered with an old record.

Under the step, the card shows how far your change has got, for example "2 of 3 name servers have your DNS change", and lists each name server as "Has it", "Not yet" or "Didn't answer".

Message What to do
"Every name server for your domain has your DNS change." Nothing.
"Every name server for your domain that answered has your DNS change. We went ahead without the one that didn't answer." Nothing.
"Your DNS change has reached 2 of your domain's 3 name servers, but ns3.example.net still has an A record that doesn't point to us. We'll set up HTTPS once all of them have it, usually within an hour. If it's still waiting after that, check that the DNS provider behind ns3.example.net has the same record, or remove it from your domain's name servers if you no longer use that provider." Wait up to an hour. If it doesn't clear, fix the record at the provider behind the named server, or remove that server from your domain.
"Your DNS change hasn't reached your domain's name servers yet: ..." The same, when none of them has it yet.
"We couldn't reach 1 of your domain's 3 name servers to confirm your DNS change. We'll keep trying, and go ahead without it 30 minutes after the domain was added. There's nothing you need to do." Nothing.
"Remove the AAAA (IPv6) record for app.example.com that doesn't point to us. We can't set up HTTPS while it's there. We'll check again automatically." Delete the AAAA record for that name.
"Remove the A records for app.example.com that don't point to us. We can't set up HTTPS while some visitors are sent elsewhere. We'll check again automatically." Delete the old A records for that name. The message says "A and AAAA (IPv6) records" when both kinds are left.
"We couldn't ask your domain's name servers directly, so we went ahead with what public DNS shows." Nothing.
"We're still asking your domain's name servers about your DNS change. We'll keep checking in the background; check again in a few minutes." Nothing to change; check again later.

The names and counts in these messages are your own. What a name server can still have instead of your record:

  • "doesn't have the record": the provider behind it hasn't got the CNAME
  • "still has an A record instead of the CNAME" or "an AAAA (IPv6) record instead of the CNAME"
  • "still has an A record that doesn't point to us" (or the AAAA or both versions)
  • "still has a CNAME that points somewhere else"

Two common causes:

  • You moved DNS providers recently, or listed name servers from two providers at your registrar. The old provider still answers with the old record. Either add the CNAME there too or remove its name servers from the domain.
  • An old A or AAAA record is still there. Delete it. Visitors whose resolver picks that record would reach the old server, so HCode waits.

Once a domain has passed this step it isn't asked again ("Your domain was confirmed before, so we don't compare its name servers again."). A proxied domain skips it ("Your domain reaches us through something in front of it (a CDN, a proxy, or your DNS provider's proxied setting), so there are no DNS records to compare.").

Connection to your app

Message What to do
"We've connected your domain to your app." Nothing.
"Your domain is still connected to your app while you fix its DNS." A domain that worked before stays connected. Fix the DNS record step.

Security certificate and HTTPS

These steps check the certificate and that your site answers over HTTPS. Their messages are explained in HTTPS certificates. Two you may see here:

  • "We'll check the security certificate once your site answers over HTTPS." The HTTPS step has the problem; read that one.
  • "Your domain is connected. We're still checking HTTPS; we'll keep checking in the background." The HTTPS check took too long this time. Check again later.

Messages from the page itself

Message What to do
"We couldn't run the check. Try again in a minute." The check didn't run at all, so nothing about your domain changed. Try again.
"We couldn't load the DNS record for this domain. Refresh the page to try again." Refresh the page.

If a domain is still stuck after you've worked through this page, email [email protected] with the domain name and the messages under Progress.