The “Workers” subdomain can be accessed, but custom domains return an error. In this case, simply re-uploading the code is usually not helpful, because it only proves that one entry point is working, but it doesn’t guarantee that DNS, domain binding, and certificates are all ready.
This article uses Cloudflare’s managed domain binding Worker as an example. Custom domain names and Worker Routes based on existing sites represent different product paths. Before configuring, ensure you are choosing one or the other, and avoid adding conflicting rules simultaneously.
Transforming a Single Failure into a Verifiable Hypothesis
Assume that the default entry displays the new version, the root domain displays the old homepage, and HTTPS connection cannot be established for www. This is not a general “deployment failure,” but rather three entries having different statuses. First, save the status codes, content version identifiers, certificate information, and query results separately. Then, make the following assumptions: the root domain may still be handled by the old project, and www may not yet be bound or the certificate may not be ready. Each assumption has its own verification action, and does not require modifying the application code first.
A working default entry point can rule out some build and runtime failures, but it cannot prove that a custom domain’s cache has updated. If the root domain returns old content, compare response headers and control-plane ownership to distinguish an old application from a new application serving old cached content. A 200 response establishes only that something answered, not that the right application answered. A non-sensitive deployment identifier on the page lets you compare actual versions without relying on visual memory.
If the domain returns a service error but TLS is functioning correctly, proceed to investigate the routing and application; if the handshake fails, temporarily avoid analyzing the page’s JavaScript. This sequential approach reduces irrelevant operations and prevents the possibility of inadvertently fixing both problems simultaneously, making it impossible to determine which fix was effective. Instead of waiting a fixed amount of time and then randomly retrying, record the target, old value, new value, and timestamp each time a change is made, and wait for the corresponding mechanism to change.
DNS Answer: “What does this name point to?”
dig example.dev A
dig example.dev AAAA
dig www.example.dev CNAMEThe results of the query need to be interpreted in conjunction with the current product configuration. The address returned under the proxy mode may not be the traditional source server IP, and it should not be treated as the independent server address of the Worker. It is also necessary to query the authoritative DNS and multiple recursive resolvers to distinguish between configurations that have not taken effect and those where the local cache is still active.
Before making changes, record the existing record’s type, name, value, proxy status, and TTL. The domain name may also host email verification, MX, or other subdomains; do not delete the entire zone solely to fix a website issue. Only modify the specific records that have a clear conflict, and retain information that allows for rollback.
A local resolver might retain old answers, while another public resolver has already seen the new record. Querying the authoritative server can confirm the current answer at the configuration level, and recursive queries can observe the propagation of the user path. It is not possible to simply delete and rebuild the record based solely on the difference; rebuilding could further exacerbate cache inconsistencies. Negative caching also exists, where a name that previously did not exist might still be cached as non-existent. Therefore, the record’s creation time and failure type are important.
It’s also important to verify which authoritative DNS servers are being used. When adding records in the control panel, but the delegation still points to another provider, the changes will not affect the actual queries. If there is a mismatch between the DNSSEC configuration at the registrar and the zone configuration, the validating resolver may reject the answer, while the non-validating resolver may appear to be functioning normally. To verify the delegation and the chain of signatures, it’s not sufficient to have a successful resolution from a single client as evidence for all users.
Diagnostic output can include addresses, TTLs, and status without disclosing the whole zone. A zone may contain internal service names and email-verification information; retain only target-related records in the report. Separate read and write permissions too. Routine troubleshooting does not require credentials capable of deleting the entire zone. Narrower infrastructure permissions reduce recovery costs after an accidental deletion.
Domain Binding: “Which Application Should Respond?”
The custom domain in your deployment configuration must be consistent with the Cloudflare control panel status. If other Workers, Pages projects, or older site configurations are using the same name, you should first verify ownership. The “record conflict” message does not instruct you to delete all records; instead, it indicates that the same name is associated with multiple entries.
Binding the root domain and www are two specific targets. Successfully binding the root domain does not automatically guarantee that www will be accessible, and vice versa. If both entry points are available, it is important to clearly define the primary domain and the redirection strategy to avoid canonical and link generation using different addresses.
A custom domain gives a name directly to a Worker. A Route in front of an existing origin makes a Worker participate in requests according to matching rules. Choose between them based on request flow and whether an origin already exists. A personal site whose static assets are served by the Worker might use the former; an existing site needing enhancement for only some requests might use the latter. Not every control-panel field accepting a domain name represents the same kind of binding.
Routing wildcard rules can also inadvertently affect paths beyond what was intended. When adding rules for an entire domain, the email service will not use HTTP routing, but APIs, validation paths, and older applications within the same domain may be affected. First, list the existing uses of the domain name, then determine the scope of the rule. When binding the root domain and “www”, check for exact conflicts, and do not migrate any other subdomains that are not related to this website.
Versioned configurations can express the desired state, while the control panel represents the actual state. Both need to be regularly checked. If the configuration is not synchronized after manual changes, the next deployment may revert to the old state. If the configuration includes invalid domain names, the deployment may also fail. Before writing the configuration, confirm the target account and region, and ensure that the domain name string is correct. However, this does not guarantee that the resources belong to the correct account. It is important to record the Worker name, account, and public endpoint simultaneously to avoid errors caused by duplicate project names.
TLS Answer: “Is the Connection Trustworthy?”
After DNS resolution is correct, the certificate may still be in the issuance or validation phase. Check the certificate’s domain, validity period, and chain of trust. Do not confuse application return status codes with TLS handshake issues. Errors in browser caching may differ from results obtained using terminal tools. Record the specific time and client information.
CAA records can affect which Certificate Authorities are allowed to issue certificates, but you should not remove them arbitrarily just because you see certificate issues. First, verify based on platform prompts and the current certificate policy. Incorrect DNSSEC configuration can also cause some resolvers to fail, so you need to check the validation chain, not just test a single machine.
The names, validity, and chain covered by the certificate must match the access point. A successful root domain does not automatically indicate that a certificate covering the “www” subdomain has been installed; a wildcard certificate should not be interpreted as covering all levels of names. When the browser displays a certificate error, record the specific error category, rather than simply taking a screenshot showing “access denied.” The application’s response headers do not exist before TLS completion and cannot be used to fix the handshake by modifying the HTML.
Issuing certificates from the platform may depend on domain verification and DNS status, and CAA (Certificate Authority Authorization) restricts the allowed issuing authorities. First, check if the current platform’s requirements are compatible with the restrictions, and do not directly delete all CAA records. Any changes to security constraints should have a valid reason and a recovery plan. If the certificate is still pending issuance, monitor the control plane status changes; if a clear failure occurs, read the failure reason and adjust accordingly. Waiting does not replace configuration verification, and modifying the configuration cannot force immediate issuance.
Simultaneously testing different networks and clients helps identify local caching or network filtering issues, but the sample size is limited. If a company network fails but a mobile network succeeds, this could be due to the behavior of a proxy, resolver, or security device, and cannot be directly attributed to a global domain issue. By identifying commonalities and differences, you can narrow down the diagnosis based on evidence, avoiding the need to repeatedly deploy the same version.
Separate recording of acceptance times and the propagation process.
DNS modification complete, certificate ready, domain returned to the new application, and all tests passed – these events may occur at different times. Documenting evidence at each stage allows you to distinguish between successful operations and external propagation. A successful tool report upload only proves that the code has entered the platform; it does not prove that the public domain is now available. The control panel showing a successful binding does not mean that all clients have cleared their old DNS records. Users are primarily concerned with the final stage of completion. The report should clearly indicate the current stage of completion.
While waiting, repeat only read-only checks relevant to the hypothesis. If the binding is correct but the certificate is still being issued, inspect issuance status and the HTTPS handshake instead of redeploying code or changing DNS repeatedly. External state may legitimately need time to converge. Repeated writes remove stable diagnostic conditions. If the state reports a clear error, read it and adjust the precise target rather than treating waiting as a universal remedy.
When migrating, it’s also important to consider the traffic from the original site. Reducing the TTL of existing records only affects the new cache duration after the old cache expires, and cannot guarantee immediate updates for all queries after the switch. The behavior of platform proxies and custom domains may also differ from a traditional site migration, and must be explained based on the actual product. Do not assume that the propagation time mentioned in a general DNS tutorial is a service commitment for your current configuration.
Define escalation paths for failures:
- Incorrect application version: Check deployment ownership.
- Failed validation: Check delegation and signature.
- Failed handshake: Check certificate.
- Business errors with correct version: Check application logs.
You can consolidate the evidence into a concise incident record, including the start time, precise target, impact scope, validation results, and recovery actions. This is not to add extra steps for minor changes, but to prevent the next maintainer from having to redo all the guesswork.
Finally, ensure that essential services like the verification email remain unchanged. The website binding should not modify MX, TXT verification, or other subdomains. Taking snapshots of the relevant records before and after the modification can demonstrate the scope of the changes. When you have full administrative control over the entire domain, it’s crucial to use precise targeting. Successfully opening the website while simultaneously disrupting email services should not be considered successful domain configuration.
Separating Three Failures with a Single Evidence Table
Assuming the authoritative server responds correctly, the public recursive resolver “A” returns a new result, and resolver “B” still doesn’t exist, the browser displays a certificate error. Do not attribute these to a single DNS issue. The evidence table records the client, query target, failure stage, time, and direct observations, row by row: Resolver “B” hasn’t seen the name, indicating a problem with the resolution path; the connection reached the edge but the certificate name didn’t match, indicating a TLS issue; an error occurred after the handshake, indicating a routing or application issue. The subsequent action for each row is different.
The query tool also requires clarification on where the answers are obtained. The authoritative server verifies the current configuration, the recursive resolver observes the cache path, and the system resolver observes the actual configuration used by this machine. Corporate proxies or browser security DNS may differ from the system resolver. When the terminal is functioning normally but the browser is failing, record whether the browser is using a proxy or a standalone resolver, rather than continuing to modify the correct zone records. The tool’s success is a sample and cannot replace real user entry validation.
For SERVFAIL, distinguish validating resolvers from non-validating paths. A broken DNSSEC chain can make some resolvers reject answers even when direct authoritative queries succeed. Check registrar delegation, DS records, and zone-signing state. Do not disable security mechanisms without evidence. Domain administration often spans two platforms: one showing a feature as enabled does not prove the other is consistent with it. Record the relevant relationships, not just a screenshot from one console.
Regarding NXDOMAIN: Verify the exact domain name and zone delegation, then check for negative caching. Since the root domain and “www” have different creation times, you cannot infer the existence of “www” from the root domain. When considering timeouts, consider both network accessibility and the availability of the DNS resolver itself. Do not equate timeouts with domain non-existence. Accurate classification allows for appropriate waiting and adjustments: caching propagation can be waited for, delegation errors require precise adjustments, and network outages require path verification.
Before accessing the migration entry point, verify the domain’s HTTP responsibilities.
A root domain may provide article paths, APIs, authentication callbacks, and certificate-validation endpoints at once. Before migrating to a new Worker, list who currently handles each path and whether the new architecture supports it. Checking only the homepage can leave articles working while OAuth callbacks fail or webhooks receive a static not-found page. Domain ownership is a name-level decision; request functionality is a path-level responsibility. Document both.
The choice of route and custom domain name can be inferred from this. If you need to preserve an existing source site while enhancing only a portion of the path, route matching is more likely to meet the requirements. If the entire name is provided by the worker, direct binding may be more explicit. The actual priority and interactions must be determined by reviewing the current platform documentation and the control panel status, not based on rules remembered. The migration plan should record the old objects that are being removed and the old services that are being retained, and should not automatically clear all configurations.
First verify the new application’s required paths through a temporary entry point, then switch the precise target. This does not prove that production certificates and routing are ready, but it narrows application-level uncertainty. After switching, exercise each responsibility on the original list using synthetic authentication and webhook payloads where appropriate. Do not blindly test production write endpoints. If a task cannot be executed safely, verify routing and deployment configuration and explicitly leave functional acceptance pending rather than pretending it was tested.
Certificate Diagnostics: Clearly State the Actual Handshake Name
The network address a client connects to and the name TLS verifies are different concepts. Even through a proxy address, certificate validation concerns the requested domain. Browsing directly to an edge IP generally does not reproduce the normal entry point. Use diagnostic tools that let you specify the server name and inspect name coverage and certificate chains. A successful request with certificate validation disabled does not prove that HTTPS is secure; it can only help separate some network failures from certificate failures.
Machine clock errors can also affect the validity determination. If a single client believes a certificate is not yet valid or has expired, it should first verify the local time against other controlled clients. The behavior of the certificate chain in different client trust stores may also vary. The reporting should focus on the supported range rather than representing all devices with a single new browser. If the target user is using a specific corporate proxy, it is also necessary to consider the proxy certificate and not directly attribute any issues to the platform’s failure to issue it.
For each certificate, record its current names, issuance status, expiry, and management responsibility. Platform-managed renewal reduces routine work but does not remove the need to notice failures. Expiry alerts should cover actual public entry points. An old domain that redirects still needs valid HTTPS because the browser must complete its handshake before receiving the redirect. Retaining responsibility for the old domain’s registration renewal and certificate is part of keeping migrated links reachable long term.
Report control-plane changes and reachability acceptance separately
Once the API accepts a binding operation, you can record “configuration write succeeded.” Do not report “website is live” until you have received the correct HTTPS body. Reporting these stages separately tells the next maintainer whether propagation, certificate issuance, or application behavior remains unresolved. Query status at bounded intervals rather than repeatedly executing writes. Unchanged external state is not a reason to change more configuration.
If the operation fails, save the precise error category and the target object, but do not record the management token. Rollback requires the ability to restore the previous binding and verify that the old application version is still readable. Revoking a new configuration does not automatically restore all previous relationships. The final evidence table includes the root domain, www, default entry, and key paths, making it clear which scope the changes apply to. Finally, check any unaccessed email records to prove that the operation did not expand to infrastructure that users did not request.
Layer-by-Layer Verification, Changing Only One Factor at a Time
First request the Worker’s default entry point and verify its application version. Then query the target name to confirm DNS resolution, check the control-plane binding, and finally request HTTPS. Record the status, response headers, and identifying body content. An old application returning 200 does not count as a successful deployment.
curl -I https://example.dev/
curl -I https://www.example.dev/writing/curl -I tests only HEAD. Some applications handle HEAD and GET differently, so fetch the actual page during acceptance too. Check critical paths and RSS, not only the homepage. For redirects, verify that Location preserves the path so www deep links do not all collapse onto the root page.
After deployment, bind the domain name to the versioned configuration or record the specific operation, and verify it against the control plane status. This prevents conflicts from recurring due to missing domain names in local configurations during the next deployment. Modifying DNS is an infrastructure change that should have a defined goal, evidence, and rollback plan, rather than repeatedly clicking until the page happens to open.
Construct a dual-stack counterexample: IPv4 succeeds while IPv6 fails. Save the A and AAAA answers and the stages of each connection separately. Determine whether failure occurs during resolution, the handshake, or body delivery. A traditional origin migration that leaves an old AAAA record behind may send some clients to the old entry point. Platform proxy products can manage addresses differently, however. Do not delete AAAA records merely because you observe this symptom. First establish who manages those records and what the product requires.
A browser may automatically try different connection paths, allowing eventual success to hide persistent failure on one path. Controlled tools can select each address family and record the connection target while retaining the correct TLS name and HTTP host. Do not substitute direct IP browsing for this test: it changes certificate and routing inputs. Hold the observation time and target article consistent when comparing paths so overlapping releases are not mistaken for network differences.
The fix only applies to objects with confirmed errors, followed by repeating both paths and retesting the previously failed network. If one of the networks is unavailable in the test environment, the report indicates “Not covered,” and the other successful path is not expanded to a dual-stack completion. This sample ensures that the reachability conclusions cover the range of connection paths; the ownership verification of the root domain, “www,” and the default entry remains independent.
References: Workers Custom Domain Name, Cloudflare DNS Troubleshooting.