Skip to main content

A practical website diagnostic workflow

Website not loading? Separate DNS, TLS and HTTP before changing anything.

Find which layer needs attention with three existing QZX commands. Check name resolution, certificate validity and the response from a specific URL, then turn the results into an actionable incident briefing.

Created and maintained by Alejandro Sánchez · QZX — Quick Zap Exchange

Run the complete workflow

Install QZX

These commands are available in the published Alpha 0.2.2.0.8. Use standard Python >=3.11 and verify the installed version before running them. No account or API key is required.

python -m pip install --upgrade qzx
qzx version --json

Need pipx or help with your Python environment? Choose an installation path.

Run the complete workflow

Prepare the commands below, or replace example.com manually with your hostname and a safe, read-only HTTPS page. DNS and TLS take a hostname, not a URL. Run each line separately in your terminal; the HTTP timeout is 10 seconds, not a deadline for the whole workflow.

qzx checkDns example.com --json
qzx checkSslCertificate example.com 443 --json
qzx checkUrlStatus https://example.com 10 --json

These probes contact DNS resolvers and the remote server. They do not change DNS, replace certificates or edit server configuration. Do not target URLs that trigger actions, and review hostnames, query strings and returned data before sharing a report.

1. Does the name resolve?

Read records.A, records.AAAA, record_status and errors. A missing AAAA or MX record alone does not prove a website outage. query_failed means the query was inconclusive; dns_name_not_found is a different result. Partial answers can coexist with success: true.

DNS command reference

2. Is the certificate valid here?

Check is_valid, chain_trusted, hostname_match and days_remaining. An inspected but invalid certificate can return success: true and is_valid: false. Check the local clock and trust store as well as the remote certificate; never disable validation to turn a failed check green.

TLS certificate reference

3. What does this URL return?

Read is_online, status_code, status_detail and response_time_ms. The command follows ordinary redirects and reports the resulting response, not a full redirect trace. It does not render JavaScript or log in to the application.

HTTP status reference

A completed check is not a healthy website

success and the process exit code describe execution of the diagnostic. They are not a substitute for the DNS evidence, is_valid or is_online. In particular, a received HTTP 404 can produce exit code 0, success: true and is_online: false.

Recorded, not invented

Excerpt captured from the published QZX 0.2.2.0.8 wheel on standard CPython 3.13.13, Windows x64. A temporary local HTTP endpoint intentionally returned 404. This is a controlled fixture, not an outage of example.com or QZX.

{
  "success": true,
  "is_online": false,
  "status_code": 404
}
Read full JSON, runtime and wheel fingerprint
DNS name not found or every query failed
Check spelling, local resolver/network access and authoritative DNS. Do not change hosting based only on a failed lookup.
Certificate inspected, but is_valid is false
Read the trust, hostname and date fields. Resolve the reported cause before relying on this TLS connection.
HTTP 401 or 403
A server or intermediary replied. Check access rules and authentication; this is not proof that the server is offline.
HTTP 404
Check the exact path, routing and deployment. The endpoint replied, but did not provide the requested resource.
HTTP 5xx, or no status_code
For 5xx, inspect application/proxy logs you control. With no HTTP response, separate DNS, connection, TLS and timeout evidence in status_detail.
HTTP 2xx/3xx and a valid certificate
This probe reached a responding endpoint. Check the real user journey separately; a login page, cached page or broken JavaScript can still return 200.

Give an agent an incident briefing, not permission to improvise

Using these three QZX results, identify the earliest layer with evidence of a problem. Distinguish a failed diagnostic from an unhealthy target and an inconclusive query. Cite the actual fields, separate facts from assumptions, and propose one next check. Do not change DNS, certificates, firewall rules or deployments. Do not claim the application works merely because HTTP returned 200.

Prefer terminal text? Remove --json. Need complete JSON? Keep it and inspect each command independently; do not merge several JSON documents and call them one valid JSON file.

Keep the evidence in scope

Results describe this machine and this moment. A CDN or proxy can answer while the origin is unavailable; a firewall may treat this CLI differently from a browser. This workflow is not continuous monitoring, a browser test, a load test or a security audit. Repeat a bounded check from an authorized second network when the location matters.