A methodical curl debugging session

A useful curl session answers one question at a time: did a connection open, did an HTTP response arrive, and where was the time spent?

Keep the first request simple

Begin with a known local endpoint. The following request assumes an HTTP service is already listening on loopback port 8000. If no service is running, a connection failure is expected. Keeping the address explicit removes name resolution from this first check.

curl --verbose --connect-timeout 3 --max-time 10   --output /dev/null http://127.0.0.1:8000/

Verbose output goes to standard error and shows connection details along with request and response headers. The response body normally goes to standard output; --output /dev/null discards it here. A successful connection followed by an HTTP error is a different result from a refused connection or a timeout.

Inspect the response you received

By default, curl can complete successfully after receiving a 404 or 500 response. Use --fail when an HTTP error should fail a script. It normally suppresses the error response body. On versions that support it, --fail-with-body retains that body while still producing a failure exit status for HTTP errors.

curl --silent --show-error --dump-header -   --output /dev/null http://127.0.0.1:8000/

This second command prints response headers while discarding the body. It still performs a GET. By contrast, --head requests HEAD, and some applications handle that method differently. A HEAD result alone may therefore miss the failure observed by a browser making a GET.

Measure a complete attempt

Timing fields help narrow the next investigation. They are cumulative durations from the beginning of the transfer, rather than independent measurements to add together. Connection reuse and redirects can complicate interpretation, so start with one request to a direct URL.

curl --silent --show-error --output /dev/null   --write-out 'connect=%{time_connect} first=%{time_starttransfer} total=%{time_total}
'   http://127.0.0.1:8000/

--connect-timeout limits the connection phase, which can include name lookup and protocol handshakes. --max-time limits the overall operation. A fast connection followed by a long wait for the first byte suggests a different investigation from slow connection establishment.

Use --location only when you intend to follow redirects. For deeper inspection, --trace-ascii records transfer details, potentially including credentials and body data. Remove sensitive material before retaining or sharing a trace. Preserve the command, exit status, and relevant response headers together so the observation can be repeated.