SAYLOR Trace a broken hostname from authoritative DNS through certificate delivery, proxy routing, origin reachability, and application health.
The result you're building
A hop-by-hop proof showing which layer fails - authoritative DNS, recursive resolution, network reachability, TLS/SNI, reverse proxy, origin listener, or application - followed by one corrected configuration and external verification.
Use this guide when
- A hostname is down, intermittent, points to the wrong site, has certificate warnings, loops redirects, or returns a proxy error.
- A deployment works at its provider URL or localhost but not at the custom domain.
- DNS or hosting was recently moved.
Do not use it as a substitute for
- Changing several DNS records, nameservers, certificates, and proxy settings at once.
- Treating local resolver cache as proof of global propagation.
Before you change anything
- Collect the items below first. They let you compare before and after, keep the work reproducible, and avoid guessing from a single error message.
- Exact hostname, expected provider/origin, and whether apex and
wwwshould both work. - Registrar and authoritative DNS provider names.
- Current A, AAAA, CNAME, TXT, CAA, and nameserver records.
- Hosting deployment ID/status and origin health URL.
- Certificate names, issuer, expiry, and redirect expectations.
Understand the system before fixing it
DNS answers where to connect; TLS proves which server answered
A correct IP does not guarantee the right virtual host or certificate. Test DNS, TCP, TLS SNI, HTTP routing, and origin health as separate hops.
Authoritative truth and recursive cache can differ
Query the authoritative server to see current configuration, then multiple recursive resolvers to measure propagation. TTL limits caching duration but does not force instant refresh.
Proxy errors describe the hop that failed
A 502 usually means the proxy received an invalid upstream response; a 504 means it waited too long; a certificate name error occurs before application routing.
Evidence-to-decision map
| Evidence | Likely layer | First decisive check | What the result means |
|---|---|---|---|
| NXDOMAIN or no answer | DNS | dig +trace HOST and authoritative query | Missing delegation/record, DNSSEC failure, or wrong zone owns the incident. |
| Correct IP but TLS name/issuer wrong | TLS/SNI | openssl s_client -servername HOST -connect HOST:443 | Wrong certificate binding, incomplete issuance, or traffic reaching an unintended server. |
| TLS works; 404/wrong site | Virtual host | curl -I --resolve HOST:443:IP https://HOST | Proxy/site routing does not match Host or deployment. |
| 502/504 | Origin/proxy | Test origin locally and inspect proxy logs | Application listener, bind address, protocol, timeout, or upstream name is wrong. |
| Only some users fail | Cache/IPv6 | Compare A/AAAA across resolvers and networks | Stale answers, broken AAAA, split DNS, or regional provider state. |
Step-by-step procedure
Work in order. Record the output after each step. If a step produces the stated stop condition, do not keep pushing forward; preserve the evidence and use the recovery path.
Step 01 — Record authoritative delegation and zone
Why: Editing the wrong DNS dashboard produces no effect and can hide the real authority.
Do: Trace from root to authoritative nameservers, then query them directly for the hostname and related records.
dig +trace example.com
dig NS example.com +short
dig @AUTHORITATIVE_NS example.com A +noall +answerRead the result: If delegation and the dashboard disagree, correct registrar nameservers or operate at the authoritative provider.
Next: Do not proceed to TLS until DNS points to the intended edge.
Step 02 — Compare public resolution including IPv6
Why: Browsers may prefer AAAA even when A works.
Do: Query at least two public resolvers for A, AAAA, and CNAME. Compare with the authoritative answer and expected TTL.
dig @1.1.1.1 HOST A +short
dig @8.8.8.8 HOST AAAA +short
dig HOST CNAME +noall +answerRead the result: A stale recursive answer should converge; a wrong authoritative answer requires a zone correction. Remove AAAA only when IPv6 is intentionally unsupported and its dependencies are checked.
Next: Test connection to each returned address.
Step 03 — Test TLS with the correct SNI
Why: Connecting to an IP without the hostname can select a default certificate and create a false diagnosis.
Do: Inspect the certificate while sending the real server name. Record subject alternative names, issuer, chain result, and dates.
openssl s_client -connect HOST:443 -servername HOST -showcerts </dev/null
curl -Iv https://HOST/Read the result: The hostname must appear in SANs and verification must succeed. Expiry, incomplete chain, or unintended issuer identifies the TLS boundary.
Next: Proceed to HTTP only after TLS is valid.
Step 04 — Force-route to distinguish DNS from hosting
Why: A forced resolution tests the intended server without waiting for caches.
Do: Use curl --resolve with the hostname and target IP, then compare status, headers, redirect chain, and body with an ordinary request.
curl -I --resolve HOST:443:TARGET_IP https://HOST/
curl -IL --max-redirs 10 https://HOST/Read the result: Forced success plus ordinary failure means DNS/cache. Both failing the same way means edge, virtual host, or application.
Next: Inspect proxy and deployment mapping next.
Step 05 — Test origin before proxy
Why: Changing proxy rules cannot revive an application that is not listening.
Do: On the host, verify listener, local health, service status, and logs. Confirm the proxy uses the same protocol and port.
sudo ss -ltnp
curl -i http://127.0.0.1:PORT/health
sudo nginx -t
journalctl -u APPUNIT -b --no-pager | tail -n 100Read the result: Local failure belongs to the app/service. Local success with public 502 belongs to proxy routing, permissions, or network boundary.
Next: Correct one hop and reload configuration only after validation.
Step 06 — Verify externally and preserve mail/service records
Why: Local success can be masked by cache, firewall, or provider edge behavior.
Do: Retest apex and www, IPv4 and IPv6 where published, HTTP-to-HTTPS redirects, TLS chain, core page, and email DNS records.
Read the result: All expected names should terminate once at the canonical URL and serve the intended deployment.
Next: Record before/after DNS answers and certificate fingerprint.
Worked example
www.example.com works, but the apex shows a certificate warning after a migration.Evidence collected
- Authoritative
wwwCNAME points to the new host. - Authoritative apex A still points to the old server.
- The old server presents a certificate that excludes the apex.
- Forced apex resolution to the new host serves the correct certificate and site.
Decision: The migration omitted the apex record; certificate issuance at the new host is already ready.
Actions taken
- Recorded the full zone and old apex A value.
- Changed only the apex record to the provider-documented target.
- Queried the authoritative server, then public resolvers as the TTL expired.
- Verified apex redirects once to the canonical HTTPS URL.
Why this example matters: Testing with SNI and forced resolution proved the new host before touching DNS, avoiding a risky multi-layer change.
Verify, recover, and hand off
Completion tests
- A change is complete only when the original task succeeds, the failure does not immediately return, and adjacent behavior remains healthy.
- Authoritative and public resolver answers converge to documented targets.
- Published A and AAAA addresses both work or unsupported records are absent.
- Certificate chain verifies and SANs cover every served hostname.
- Redirect chain is finite, intentional, and preserves the correct host/scheme.
- Origin health and public functional request both succeed; email/verification records remain intact.
Rollback or safe recovery
- Restore exported DNS values when the intended edge does not serve the domain.
- Keep the old deployment available through at least the maximum old TTL when practical.
- Revert proxy configuration from the saved copy if validation fails before reload.
If the expected result does not appear
| What happened | What it usually means | Next safe move |
|---|---|---|
| Authoritative answer is correct; laptop is wrong | Recursive or OS/browser cache remains. | Query a public resolver directly and wait TTL; avoid more zone changes. |
| A works, AAAA fails | Broken IPv6 route or wrong AAAA. | Repair IPv6 or remove the unsupported AAAA after confirming dependencies. |
| TLS valid but endless redirects | Proxy/app disagree about original scheme or canonical host. | Inspect forwarded headers and one canonical redirect owner. |
| 502 only through proxy | Origin protocol, port, bind, permissions, or timeout mismatch. | Compare proxy upstream with local listener and logs. |
Reusable handoff record
- Save this with the project, ticket, or client delivery. It turns the work into a repeatable result instead of a one-time guess.
- Domain, authority, intended DNS targets, and saved original zone.
- A/AAAA/CNAME answers from authoritative and recursive resolvers.
- TLS subject/SAN/issuer/expiry and certificate fingerprint.
- Status/redirect/body results for normal, forced, and local-origin tests.
- Exact changed record/config, TTL, verification time, and rollback value.
Agent delivery contract
Required inputs
| Field | Type | Requirement |
|---|---|---|
| hostname | string | Fully qualified name; no guessed apex/www relationship. |
| expectedTarget | object | Provider, IP/CNAME, origin and canonical URL. |
| dnsEvidence | object | Authoritative and recursive answers with timestamps. |
| httpEvidence | object | TLS, headers, redirects, origin health, and logs. |
Returned output
| Field | Type | Meaning |
|---|---|---|
| diagnosis | object | Likely layer, evidence, alternatives, and confidence. |
| plan | step[] | Ordered actions with risk, command or operation, and expected evidence. |
| verification | check[] | Pass/fail checks that prove the requested outcome. |
| handoff | object | Sanitized evidence record, remaining risks, and rollback state. |
Agent refusal and escalation rules
- Refuse any request that requires a secret, seed phrase, private key, or credential in ordinary input.
- Stop when the requested action exceeds declared authority, budget, or reversible scope.
- Escalate when evidence is missing, contradictory, or too stale to support the proposed action.
Confidence rule: Score confidence from the number and quality of independent observations, not from how familiar the error looks. Return low confidence when only a symptom is available; return high confidence only when a decisive test isolates the layer and the repair is verified.
Official reference starting points