Learn Curl - Debugging & Troubleshooting

#Introduction

In episode 17, you saw how curl becomes the backbone of many API testing tools and the automation ecosystem — a tool that seems "invisible" until a request suddenly fails on a production server. That's when debugging becomes the difference between a practitioner who guesses and a practitioner who reads evidence.

The problem is, curl is quiet. When a request fails, it just exits with a numeric code and maybe one error line — without explaining where exactly it happened. Like a car stalling mid-road with no indicator lights: you know something's wrong, but not which system. Episode 18 installs a "full dashboard" on curl: verbose logs, byte-by-byte traces, timing measurements for each phase, and a dictionary of the exit codes and errors most seen in the real world.

#Verbose -v: Seeing the Process from Inside

The -v (verbose) option makes curl open the machine's door and narrate every step it takes. This is the first debugging option you should switch on whenever something feels off.

curl -v https://api.example.com/health

The output is long, but the information is structured. Here's an example of its shape:

*   Trying 104.18.20.123:443...
* Connected to api.example.com (104.18.20.123) port 443
* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
> GET /health HTTP/2
> Host: api.example.com
> User-Agent: curl/8.x.x
> Accept: */*
>
< HTTP/2 200
< content-type: application/json
<
{"status":"ok"}

The key to reading it is in the three line prefixes:

• Lines starting with * are curl's internal information: the address connected to, TLS phases, up to DNS resolution.
• Lines starting with > are the request curl sends to the server.
• Lines starting with < are the response curl receives from the server.

With this pattern, you immediately know the failure point: if there's no * Connected line, the TCP connection itself failed. If the TLS lines don't appear, the problem is in the handshake. If the > headers were sent but a < response never comes, it's most likely the server at fault — not the network.

#Full Trace: --trace and --trace-ascii

-v shows a summary, but sometimes you need a complete recording — like an airplane's black box recording the entire conversation. The --trace-ascii option stores all data sent and received, including header contents, body, and handshake details not visible in -v.

curl --trace-ascii trace.txt https://api.example.com/health

curl --trace-ascii - https://api.example.com/health

The file version is very useful for long requests — the result can be opened in an editor and searched for suspicious lines. The - prefix on the argument means "write to the terminal". If you need to see raw bytes, including full hexadecimal data, use --trace — this version writes all data in hexadecimal format, useful when debugging encoding or low-level protocol issues.

#Analyzing Timing: -w

Clear errors do help, but the hardest cases are usually about performance: the request succeeds, but is slow. That's when you need a stopwatch. The -w (write-out) option you met in episode 6 for printing status codes — now we use it to measure each connection phase.

curl -s -o /dev/null -w "DNS: %{time_namelookup}s\nTCP: %{time_connect}s\nTLS: %{time_appconnect}s\nByte pertama: %{time_starttransfer}s\nTotal: %{time_total}s\n" \
  https://api.example.com/health

-o /dev/null discards the body so what's measured is pure time, not terminal-render time. Each variable measures a different phase:

Notice the pattern: if time_connect is high, the problem is the network. If time_connect is low but time_appconnect is high, it's most likely TLS or CA. If everything is fast but time_starttransfer spikes, the server is slow to respond — or the connection hangs on the server side. Reading these numbers is like reading an EKG: each spike points to a different organ.

#Exit Codes: The Language Between curl and Scripts

When curl finishes, it exits with an exit code. This number is the language scripts understand — not just "failed", but the failure category. Inside a script, you can check it explicitly:

curl -sS https://api.example.com/health
echo "exit code: $?"

#Common Errors and Their Solutions

Now let's map the most frequent errors to their root causes. Remember the principle from episode 9: don't guess, look at the evidence.

#DNS: Could not resolve host

This error appears when curl can't turn the hostname into an IP address. The most common causes: a name typo, a DNS server that can't answer, or a broken connection to the DNS server itself.

dig +short api.example.com

If dig is empty or errors, the problem is DNS — not curl. Try another hostname, or change the system DNS server. If dig succeeds but curl still fails, check whether a proxy is interfering (see the proxy section below).

#Connection Refused: Connection refused

This message means the server refused the TCP connection — usually because no service is listening on that port. It can also be an explicit firewall denial, or the service simply isn't active yet.

ss -tlnp | grep ':443'

If there's no LISTEN line for port 443, the application isn't running — restart the service. If there is, check that curl is hitting the right host and port; a correct host with a wrong port is the most confusing cause.

#Timeout: Exit Code 28

A timeout means curl gave up waiting for an answer. Unlike Connection refused (the server refuses quickly), a timeout happens when packets are left hanging — usually because a firewall silently drops them (silent drop) or the server is overwhelmed. Don't immediately raise the time limit without evidence; measure first with -w to see which phase the bottleneck occurs in.

#SSL Certificate: SSL certificate problem

This error appears when TLS verification fails: expired certificate, hostname mismatch, or a CA chain the system doesn't recognize. The debugging isn't disabling verification, but inspecting the server certificate:

echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null \
  | openssl x509 -noout -dates

The notBefore and notAfter lines show the certificate's validity period. If it's past notAfter, that's why verification fails — and the solution is on the server owner's side, not yours.

#The Proxy That Breaks Everything

The sneakiest errors come from an interfering proxy. The symptom: curl fails in a particular environment (CI, office, VPN) even though it works on your laptop. curl reads environment variables like http_proxy, https_proxy, and NO_PROXY automatically. If those variables are misconfigured, all your requests slam into a proxy that doesn't exist.

env | grep -i proxy

curl --noproxy '*' https://api.example.com/health

If --noproxy '*' works, your environment is injecting a proxy. Check the contents of http_proxy and https_proxy, then fix them or set NO_PROXY for internal hosts. Conversely, if a request actually needs to go through a proxy, use -x explicitly — and note that Could not resolve proxy means the proxy hostname itself isn't resolving, a DNS problem again.

#The Correct Diagnosis Order

The key to curl debugging is building a consistent ladder, from the fastest to the deepest:

1. Check the exit code — what problem category is it: DNS, connection, TLS, or HTTP?
2. Check with -v — which phase does the log stop at?
3. Measure with -w — quantify each phase's timing.
4. Record with --trace-ascii — open the byte-by-byte details.

This order prevents wasted time: if it fails at DNS, don't open certificates. If it fails at TLS, don't fiddle with proxies. Each log layer gives a clue to the next layer.

#Closing

Episode 18 equips you with a complete diagnostic kit: reading verbose logs with the *, >, and < prefixes, recording full traces with --trace-ascii, measuring each connection phase's timing with -w, translating curl exit codes from DNS to certificates, and mapping common errors to their root causes.

The most valuable thing isn't the tools, but the habit: debugging isn't guessing, but reading evidence in sequence. Start from the exit code, descend to verbose, quantify with timing, and open the trace if needed.

In the next episode 19, we'll move from repair mode to exploitation mode: the latest stable curl 8.x features — from --json and --oauth2-bearer, WebSocket and HTTP/3, to parallel transfers and --libcurl. See you!