Custom-domain onboarding: explain what DNS verification is waiting for
Separate saved settings, observed DNS records and certificate readiness so customers can understand pending custom-domain setup and find the right next action.
In this article
A custom-domain setup screen should explain which condition is still missing. “Pending” is too broad when the user may have saved the domain in your product, changed a record at a DNS provider and reached a different stage of certificate setup.
For a typical hosted-product journey, separate the requested hostname, the DNS information your system currently observes and the readiness of the secure connection. Tell the user which system owns the next action. A generic instruction to wait can conceal a wrong record just as easily as it can describe a legitimate delay.
The exact DNS instructions must come from the hosting product. The design pattern is to keep those instructions and their observed state understandable while the customer moves between systems.
Saving a hostname is the first receipt
Imagine a fictional knowledge-base product connecting help.example.com. This is an illustrative domain and product journey. Saving that hostname tells the product which address the customer wants to use. It does not, by itself, establish that incoming traffic will reach the correct knowledge base.
The confirmation should preserve the full hostname and the intended destination. “Help center for the Northwind Demo workspace” is more informative than “Domain added,” because a customer managing several workspaces can check both sides of the connection.
Next, show the required record using separate fields for type, name and target. Explain where to make the change. If someone else controls DNS, provide a copyable instruction packet containing the exact hostname and product-generated values. Do not ask the current user to guess which administrator owns the domain.
The product should preserve this state when the person leaves to contact that administrator. Returning to the same setup should show the pending connection, not encourage them to create a second one.
Separate ownership, routing and certificates
Cloudflare for SaaS distinguishes hostname validation from certificate validation. Its documentation identifies separate fields for these states and says production traffic needs an active hostname, an active SSL state and DNS pointing to the SaaS target.
That is a useful model for interface design even when another platform uses different terminology. Verifying a customer’s control of a hostname, sending traffic to the intended service and preparing a certificate answer separate questions. One should not silently stand in for the others.
In our fictional help-center product, a status panel could show:
| Condition | What the product can report | Appropriate next action |
|---|---|---|
| Hostname saved | The address and selected workspace are recorded | Review the DNS instructions |
| Required record not observed | The last check did not find the requested target | Compare the saved record with the product’s exact value |
| Record observed | The checker found the expected routing record | Continue checking certificate and service readiness |
| Secure connection preparing | Routing is recognized; secure serving is not yet ready | Keep the configuration and inspect any reported certificate issue |
| Help center available | The address serves the expected content securely | Open the customer-facing page and confirm the destination |
These are proposed states, not a universal protocol. A platform may combine checks or expose fewer details. The product should state only what its own checks can establish.
A useful DNS comparison shows both values
“Invalid configuration” asks the user to investigate without telling them what the product saw. A better diagnostic view places the expected value beside the observed value and includes the time of the check.
Suppose the fictional product expects a generated target for the current workspace, but the customer has copied a value from an older setup. The comparison can make that mismatch obvious. The next step is to correct the target at the DNS provider, not repeatedly click a button that rechecks the same record.
If no matching record is observed, the explanation should leave room for uncertainty. The record may not have been saved where the domain’s DNS is actually managed, or the product’s latest check may not yet reflect the change. “We have not observed the required record” is more precise than accusing the user of doing nothing.
Vercel’s domain guide illustrates why instructions need to match the actual hostname and setup. It distinguishes apex-domain and subdomain configurations, shows product-specific record values and directs troubleshooting toward the records at the authoritative DNS provider. It also distinguishes changing a website record from moving nameservers.
A help-center connection should not casually instruct someone to move all their DNS management when the product only requires a specific record. If a broader change is required, explain its scope through the platform’s own instructions rather than burying it inside the onboarding checklist.
Explain waiting without promising a universal time
A timer can look reassuring while conveying very little. Before displaying one, decide what it measures: time since the user saved the configuration, time since your checker observed the new record, or time since certificate preparation began.
Use a timestamp and a clear refresh action when you cannot offer a meaningful estimate. “Last checked just now; the expected target was not observed” helps the user reason about a recent change. “Almost done” does not.
When a check is delayed, preserve the successful stages. A recognized routing record should stay visible while the certificate step continues. Otherwise the user may undo a correct configuration because the overall badge still reads pending.
Give the person something useful to do outside the blocked step. In the fictional help-center product, they could review the content through its existing preview address while the custom connection is prepared. Explain that the preview and custom domain are separate access paths; do not present the preview as proof that the custom address works.
Make the support handoff diagnostic
If setup remains unresolved, the support request should include the requested hostname, intended workspace, last observed record, expected record and last check time. Those details let support identify the boundary that needs attention.
Keep credential requests out of this handoff. A customer should not have to send a registrar password to explain a DNS mismatch. When the product cannot observe a relevant setting directly, ask for the specific nonsecret configuration detail needed to understand it.
For an internal acceptance review, walk through a correct record, a wrong target and a configuration that reaches routing readiness before certificate readiness. These are proposed test cases. Check whether each produces a distinct explanation and whether returning later resumes the same setup.
The final confirmation should name the actual address and invite the customer to open it. Verify the intended content and connection before presenting the domain as ready. A successful first visit is the point where the technical setup becomes a recognizable product result.
