Modulify
Dashboard

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

The badge next to your domain reads Connected only when two things are true at once: all four required DNS records resolve to the values Modulify listed, and the TLS certificate for that hostname has been issued. Anything short of that reads Pending.

This has a consequence worth knowing. Once the A and AAAA records point at your site, the certificate can be issued and the site starts answering over HTTPS, even though the _acme-challenge and _fly-ownership records are still missing. So a domain can serve your site perfectly and still read Pending.

That is not a display bug and it is not safe to ignore. Those two records are the channel the certificate renews through, so a domain left in that state works now and fails later. Add all four.

Read the record table

Open More, then Domain. 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. There are five of them.

Cloudflare proxy detected

"Disable the orange-cloud proxy for this record (set to DNS only)."

Your record resolves to a Cloudflare edge address rather than your site. In the Cloudflare DNS panel, click the orange cloud on that row so it turns grey. Proxied records break certificate issuance for this setup.

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 your site's own server. 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 and AAAA records entirely. Note the difference from the message above: Wrong value means edit, Conflicting record means remove.

The causes worth checking first

You added the records at the wrong host. The line above the table names the zone: "Add the following records 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 others read _acme-challenge and _fly-ownership. Most panels add your domain for you. Paste the full hostname into one of those and you create _acme-challenge.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.

Only some of the records are there. Partial records are the single most common reason a domain sits Pending indefinitely rather than failing loudly. All four are required. Check each row's status individually rather than glancing at the badge.

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 it warns above the table: "On Cloudflare? Set each record to DNS only (grey cloud), not proxied. Orange records break SSL."

How Modulify re-checks

While the Domain tab is open, Modulify re-resolves every record every 5 seconds. The badge and the row statuses update live without a refresh. Checking stops after about ten minutes on one domain, and it pauses while the browser tab is in the background.

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 and WWW variant reading Pending. Most people never add the www records, and the site works fine without them.

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 Configure automatically with <provider> button only appears when your DNS provider advertises support for it. GoDaddy is excluded, so its customers add the records by hand.

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, "Add the DNS records manually below!". Either way 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
You are not authorized to manage domains in this workspace! Your role lacks the Manage domains permission
Site already has a custom domain! One custom domain per site. Remove the current one 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

Starting over

If the records are right and the domain has been Pending for hours, remove the domain and add it again. The tab says "Only one custom domain can be connected at a time. Remove it to connect a different one." Removing asks for confirmation and warns that the site stops working at that address.

After re-adding, compare the values in the table against what is saved at your DNS host before assuming anything carried over.

Next