HTTP and TLS troubleshooting with curl cheat sheet
Separate DNS, TCP, certificate validation, redirects and HTTP status with bounded curl requests.
curl on Linux/macOS or curl.exe on Windows. Commands below use POSIX shell quoting; use curl.exe in Windows PowerShell.
Updated · curl · 6 min read
| Command | What it does |
|---|---|
curl --version | Identify curl features and TLS backend |
curl --head --connect-timeout 5 --max-time 15 https://app.example.com/ | Inspect the first HTTP response headers |
curl --silent --show-error --output /dev/null --write-out "code=%{http_code} dns=%{time_namelookup} tcp=%{time_connect} tls=%{time_appconnect} total=%{time_total}\n" --connect-timeout 5 --max-time 15 https://app.example.com/ | Compare request timing checkpoints |
curl --verbose --output /dev/null --connect-timeout 5 --max-time 15 https://app.example.com/ | Inspect connection and certificate diagnostics |
curl --head --location --max-redirs 5 --connect-timeout 5 --max-time 20 https://app.example.com/ | Trace a bounded redirect chain |
curl --head --resolve app.example.com:443:192.0.2.25 --connect-timeout 5 --max-time 15 https://app.example.com/ | Test one endpoint while preserving hostname checks |
Walkthrough
Replace app.example.com and 192.0.2.25 with an approved endpoint and expected IP. Requests contact the service. Commands retain certificate verification and send no authentication token.
Step 1: Identify curl features and TLS backend
curl --version
Record the version, TLS backend and supported protocols. Different builds can use different certificate stores and proxy behavior. On Windows invoke curl.exe explicitly if PowerShell resolves curl to Invoke-WebRequest.
Step 2: Inspect the first HTTP response headers
curl --head --connect-timeout 5 --max-time 15 https://app.example.com/
Read the status and Location header without following redirects. HEAD can behave differently from GET and may be unsupported, so a 405 response is not proof that normal browsing fails. Connection and total timeouts bound the attempt.
Step 3: Compare request timing checkpoints
curl --silent --show-error --output /dev/null --write-out "code=%{http_code} dns=%{time_namelookup} tcp=%{time_connect} tls=%{time_appconnect} total=%{time_total}\n" --connect-timeout 5 --max-time 15 https://app.example.com/
The timing values are cumulative checkpoints from request start, not independent phase durations. Subtract adjacent checkpoints cautiously; proxies, reuse and redirects change interpretation. On Windows replace /dev/null with NUL. HTTP 4xx/5xx can still have a zero curl exit code.
Step 4: Inspect connection and certificate diagnostics
curl --verbose --output /dev/null --connect-timeout 5 --max-time 15 https://app.example.com/
Inspect the resolved address, proxy use, TLS negotiation and certificate error if any. Verbose output can contain headers and sensitive connection details, so redact before sharing. Keep verification enabled; use NUL instead of /dev/null on Windows.
Step 5: Trace a bounded redirect chain
curl --head --location --max-redirs 5 --connect-timeout 5 --max-time 20 https://app.example.com/
Compare each status and Location with the expected canonical host and login flow. A loop or unexpected destination can explain browser failures. HEAD redirects are still not a full test of a GET request or an authenticated user session.
Step 6: Test one endpoint while preserving hostname checks
curl --head --resolve app.example.com:443:192.0.2.25 --connect-timeout 5 --max-time 15 https://app.example.com/
This pins the host/port to the selected address while retaining the URL hostname for TLS and HTTP routing. It isolates DNS selection without disabling certificate verification. An active proxy can change the connection path; inspect proxy use first.
WORKED INCIDENT
Practical case: A site fails after a DNS migration
Fictional teaching scenario; observations are examples, not captured production output.
Situation
A browser reports a certificate error after an application moves to a new load balancer.
Investigation sequence
1. Identify curl features and TLS backend
curl --versionRecord the TLS backend so differences in trust stores between the browser and CLI can be investigated.
2. Inspect connection and certificate diagnostics
curl --verbose --output /dev/null --connect-timeout 5 --max-time 15 https://app.example.com/Capture the selected destination and certificate failure. In this example the default DNS path reaches an old endpoint with the wrong hostname certificate.
3. Test one endpoint while preserving hostname checks
curl --head --resolve app.example.com:443:192.0.2.25 --connect-timeout 5 --max-time 15 https://app.example.com/Pin the expected new endpoint while preserving app.example.com. The example succeeds with normal verification.
4. Trace a bounded redirect chain
curl --head --location --max-redirs 5 --connect-timeout 5 --max-time 20 https://app.example.com/Trace the redirect chain on the intended path and confirm that a later redirect is not sending users back to the old hostname.
Example findings
Illustrative findings: default request fails hostname verification; the --resolve request to the approved new address returns HTTP 200 with certificate verification enabled.
Interpret the findings
The result supports an endpoint-selection or DNS-transition problem. It does not prove the authoritative record is wrong; a recursive cache, hosts override, split DNS or proxy can select the old endpoint.
Verify the outcome
After the approved DNS/load-balancer correction and applicable cache expiry, repeat the default request without --resolve. Verify the certificate, final URL and normal browser session from affected networks.
Escalation handoff
Send the hostname, resolved addresses, error text, TLS backend and pin-test result to the DNS/load-balancer owner. Do not solve a hostname error by disabling certificate checks.