curl --max-time / --connect-timeout: Bound Requests
curl can wait a long time by default, which is how a step hangs forever.
Timeouts turn an indefinite hang into a clean, fast failure you can retry. Two flags cover the connect phase and the whole transfer.
What it does
--max-time <seconds> sets the maximum time the whole operation may take; curl aborts with exit 28 when exceeded. --connect-timeout <seconds> limits only the time spent establishing the TCP/TLS connection, not the full transfer. Both accept decimal seconds. Use them together: a short connect timeout to fail fast on dead hosts, and a longer max-time for the data.
Common usage
curl --max-time 30 https://api.example.com/x
curl --connect-timeout 5 --max-time 60 https://api.example.com/x
curl -fsS --connect-timeout 5 --max-time 30 --retry 3 https://api.example.com/healthFlags
| Flag | What it does |
|---|---|
| --max-time <s> | Cap the entire operation; exit 28 on timeout |
| --connect-timeout <s> | Cap only the connection setup phase |
| -m <s> | Short form of --max-time |
| --speed-time / --speed-limit | Abort if throughput stays below a floor |
In CI
Always set --max-time on network calls in pipelines so a stuck dependency cannot hang the whole job until the runner kills it. A pattern that works well: --connect-timeout 5 to bail fast on unreachable hosts, --max-time sized to the payload, plus --retry to recover from transient timeouts.
Common errors in CI
curl: (28) Operation timed out after 30000 milliseconds means --max-time was hit; raise it for large downloads or add --retry. curl: (28) Connection timed out means the host was unreachable within --connect-timeout; check the network or DNS.