Troubleshoot a domain
What a Pending domain means, how to read the record table, and the causes worth checking first.
On this page
A domain that will not turn green is almost always a DNS problem, and the record table in the Domain tab tells you which one. Work down this page in order.
What Pending actually means
A Connected badge appears next to a domain only when two things are true at once: every DNS record in its table resolves to your site, and the TLS certificate for that hostname has been issued. Until then there is no badge, and each row of the record table carries its own status.
A root domain needs one A record. The www hostname or a subdomain needs one CNAME. When the record is right, the certificate usually follows within a minute or two, so a short Pending right after you add it is normal.
Read the record table
Open More, then Domain. Every domain has its own card with its own table, and each record row carries its own status while the tab is open.
| Status | Meaning | What to do |
|---|---|---|
| Valid | The record resolves and holds the expected value | Nothing |
| Pending | Nothing resolves at that name yet | Wait, or check that you saved the record |
| Invalid | Something resolves at that name, but it is wrong | Read the red banner below the row |
| Unknown | The lookup did not come back at all | Reload the tab and look again |
An Invalid row expands into a banner naming the exact problem. A row turns Invalid only after the same problem shows up on three checks in a row, checked against your DNS host's own nameservers, so it can read Pending for a few seconds first. There are six banners.
Cloudflare proxy detected
"Set this record to DNS only (grey cloud) until the domain connects. You can turn the proxy back on after that."
Your record resolves to a Cloudflare edge address, and the domain did not answer Modulify's check through the proxy. In the Cloudflare DNS panel, click the orange cloud on that row so it turns grey. Once the domain reads Connected you can turn the proxy back on, with Cloudflare's SSL/TLS encryption mode set to Full or Full (strict).
Extra record
"This name also has an AAAA record pointing at 2001:db8::1, so some visitors never reach your site. Delete it."
Your record is right, but another record at the same name sends some visitors elsewhere. It is usually an AAAA record from a previous host, or a second A record your registrar created for a parking page. Delete the record the banner names and keep yours.
At Namecheap the extra A address usually comes from a URL Redirect Record at @, often left by the parking page. Advanced DNS lists it as URL Redirect Record, not as an A Record, so delete that row.
Wrong IP address
"This points to an address that will not route to your site. Update it to the required value shown above."
The record points at an address on the hosting platform, but not at Modulify. Copy the value from the table again and replace what is there.
DNS still propagating
"Your DNS record is correct but a previous value is still cached by public resolvers. This usually clears within an hour."
This one is amber rather than red, and it needs no action. Your record is right and the old answer is still being served from caches.
Wrong value
"This name already has an existing A record pointing at 1.2.3.4. Update it to the required value shown above."
A record of the correct type is there with the wrong value. Edit it. This is the usual state of an apex A record that still points at a previous host.
Conflicting record
"An existing CNAME record at this name (old.example.com) cannot coexist with the A record above. Remove it first."
This one really does mean delete. A CNAME cannot sit at the same name as any other record type, so a leftover CNAME at your apex blocks the A record entirely. On a CNAME row, for www or a subdomain, it is usually the other way round: an old A record at that name blocks the CNAME. Note the difference from the message above: Wrong value means edit, Conflicting record means remove.
The causes worth checking first
You added the record at the wrong host. The line above the table names the zone: "Add the following record at the DNS host that manages example.com (not any other domain)." That is whoever runs the nameservers for the domain today, which is often not the company you bought it from.
Your provider appended the domain twice. Modulify shows names relative to your domain, so the apex reads @ and the www row reads www. Most panels add your domain for you. Paste the full hostname into one of those and you create www.example.com.example.com, which resolves to nothing and looks identical to having forgotten the record. Check the record's saved name, not the value you pasted.
An old record is still there. The root needs its A record pointing at Modulify and nothing else at @ pointing somewhere different. A leftover AAAA record or a second A record makes the row read Invalid with an Extra record banner. Delete the one it names.
The site has never been published. A connected domain still needs something to serve. Publish once, then look again.
The domain is on Cloudflare and proxied. If Modulify detects Cloudflare nameservers, the table shows a Proxy column reading Off, because each record has to be DNS only (grey cloud) until the domain shows Connected. With the proxy on before the first certificate exists, and Cloudflare's Always Use HTTPS enabled, the certificate cannot be issued. Switch the record to DNS only, wait for Connected, then turn the proxy back on.
How Modulify re-checks
When you open the Domain tab, Modulify checks every domain once. After that, every 5 seconds a round re-resolves the records of each domain that is not fully connected, one domain after another, and leaves connected domains alone. The row statuses and the Connected badges update live without a refresh. Each domain gets 120 checks, about ten minutes when it is the only one waiting and longer when several are, and checking pauses while the browser tab is in the background. A domain whose hostnames change, for example when you add its www variant, starts a fresh count.
If you left the tab open a long time, leave the Domain tab and come back to it to start a fresh round of checks.
DNS changes usually appear within minutes. Some providers take hours. The tab reminds you: "DNS changes can take a few minutes to propagate."
The www hostname is a separate problem
Adding a custom domain also attaches its www companion, so it is completely normal to see the root reading Connected while the record under that domain's WWW variant still reads Pending. Most people never add the www record, and the site works fine without it.
If you do not want the www hostname at all, remove it on its own row rather than leaving it Pending. See www and apex domains.
One click setup did not help
The Connect with <provider> button, in the strip at the top of a domain's card, only appears when that domain's DNS provider supports one-click setup. When it is missing, or clicking it shows One-click setup not ready yet because the provider has not switched it on for Modulify, add the records by hand. One click writes the records for the domain and its www variant, so a WWW variant left on Pending on the same card is not waiting on a second button. Each other domain on the site has its own button, and clicking one never changes another domain's records.
If the popup is blocked, the toast reads Popup blocked, "Allow popups to configure your domain automatically!". If Modulify cannot build the request, it reads Automatic setup unavailable with the reason, for example "DNS records are not ready yet. Please try again in a moment." If your provider reports that you cancelled, it reads Automatic setup cancelled, "No DNS records were changed. You can still add them manually below." If your provider reports another problem, it reads Automatic setup did not finish, "Your DNS provider reported a problem. Check the records below!". In every case the manual table below is always there and always works.
Errors when adding the domain
| Message | Cause |
|---|---|
| A paid plan is required to add a custom domain! | Custom domains are a paid feature. On a free workspace the field is disabled and the section carries a Paid badge |
| A paid plan is required to manage domains! | Adding a www variant or finishing a domain verification needs a paid plan too. On a free workspace Add www, Add root and Verify & Connect are disabled, and removing a domain still works |
| You are not authorized to manage domains in this workspace! | Your role lacks the Manage domains permission |
| A site can have up to 10 custom domains! | The site already has 10 domains. Remove one first |
| example.com is already connected to this site! | The hostname is already on this site, as one of its domains or as the www variant of one |
| example.com is already connected to another site! | Another site holds that hostname. Remove it there, or delete that site, first |
| You cannot use a Modulify domain as a custom domain! | The address you entered is on a Modulify-owned domain |
| Domain should not include http:// or https://! | Enter the hostname on its own, for example example.com |
| Domain should not include a path! | Drop everything after the hostname |
| Domain must be between 4 and 253 characters! | The value is too short or too long to be a hostname |
| Domain must be a valid domain! | The value is not a well formed hostname |
This domain is not connected to the site! comes from Remove or Add www on a domain that was removed in the meantime, for example from another tab or by an AI client. example.com does not have a WWW variant! is the same case for a www variant: it was removed in the meantime, so there is nothing left to remove.
The domain is green but some people cannot reach it
A domain can read Connected, serve correctly from everywhere you test, and still fail for a handful of visitors. In Safari they see "Safari can't open the page because the server can't be found", and in Chrome an equivalent message. If the same person succeeds later, or on a different network, with nothing changed at your DNS host, the fault is not on your side.
Some networks refuse to resolve whole domain endings. Corporate firewalls, school and carrier filters and a few consumer routers block the newer endings that attract the most abuse, among them .lol, .bid, .website, .top and .xyz. The block is on the ending, not on your site, so nothing in the Domain tab changes it. It follows whichever network the visitor is on, which is why it reaches some people and not others, and why it clears when they move between mobile data and Wi-Fi.
Two ways to tell this apart from a real fault:
- Ask the person to try the same address on mobile data and on Wi-Fi. Working on one and not the other usually means filtering rather than a broken record.
- Open the site yourself from a network you do not control. If it loads there, your records are fine.
No setting fixes this. A domain on a mainstream ending such as .com, .org, .io or .co reaches more people. Modulify shows a note under the field when you type a domain on an ending that is commonly filtered, and again on that domain's card once it is added.
Starting over
If the records are right and the domain has been Pending for hours, remove that domain and add it again. Removing asks for confirmation and warns that the site stops working at that address. The site's other domains keep working while you do.
After re-adding, compare the values in the table against what is saved at your DNS host before assuming anything carried over.
Next
- DNS records explains what each record does.
- Connect a custom domain walks the setup again from the start.
- Your free web address always works, even while a custom domain is Pending.