15 curl errors on a screenshot call, with fixes
Every message here was printed by a real curl run, not written from memory. Paste yours, or just its number, and get the cause and the fix.
- exit 28Operation timed out
A time limit ran out before the answer was complete.
Fix: Give curl more time than the render can take: set --max-time to the API timeout plus a margin. 100 seconds covers the largest timeout of 90.
The answer was lost
Read the whole entry
Where on the way did the call break?
A screenshot call travels from your command to a file in four steps. The exit code tells you which step failed, and each step has its own kind of fix.
Nothing was sent
curl stopped on your machine. The address, the shell or a file is wrong, and no packet left.
The server was not reached
curl tried to open a connection and could not, or did not trust what answered.
The answer was lost
The connection opened, then it was too slow, was cut, or ended early.
An answer came, but not the picture
The server answered. The status, the file or the exit code says something other than "a screenshot".
1.Nothing was sent
curl stopped on your machine. The address, the shell or a file is wrong, and no packet left.
Protocol not supported
Do not retrycurl: (1) Protocol "htp" not supported or disabled in libcurlThe text in front of :// is not a protocol curl can speak.
Why it happens
- A typo in the scheme: htp://, htps://, https// or https:/ .
- An API address variable that holds something else, such as a path or a host without a scheme.
- A curl built without that protocol. This is rare for http and https.
Other wording
- With -G and --data-urlencode, curl 8.5.0 exited 1 and printed nothing at all. The exit code is then the only sign.
Check
Print the address exactly as the shell passes it:
API_BASE="https://curlshot.com/api/v1"
printf '%s\n' "$API_BASE"Fix
- Start the address with https:// and nothing else in front.
- Quote the variable: "$API_BASE". An unquoted one can split on a space.
Retry? No: the same command fails the same way.
URL rejected: malformed input
Do not retrycurl: (3) URL rejected: Malformed input to a URL functioncurl could not read the address as a URL, so it did not connect to anything.
Why it happens
- A space, a tab or a line break inside the address. A carriage return at the end of a line read from a Windows file counts.
- An empty variable: curl "$URL" with URL set to nothing printed this same message on curl 8.5.0. Newer curl versions may word it differently.
- Smart quotes pasted from a chat or a document instead of plain double quotes.
Other wording
- Older curl: curl: (3) <url> malformed
- Programs built on libcurl often print only: URL using bad/illegal format or missing URL
Check
Show the characters you cannot see:
printf '%q\n' "$URL"Fix
- Put the whole address in double quotes.
- Pass the page you want captured with -G and --data-urlencode, and curl encodes spaces and symbols for you.
Retry? No: the same command fails the same way.
Unmatched brace in URL
Do not retrycurl: (3) unmatched brace in URL position 34:
http://127.0.0.1:18080/ok?filter={a
^curl reads { } and [ ] in an address as a pattern that expands into several requests, and this one is not closed.
Why it happens
- The page address you pass to a screenshot API contains a { or [ , such as a filter or a JSON-like query value.
Other wording
- bad range in URL position N, for an unclosed [ ]
Fix
- Add -g (--globoff) so curl sends the characters as they are.
- Or encode them: { is %7B, } is %7D, [ is %5B and ] is %5D. --data-urlencode does this for you.
Retry? No: the same command fails the same way.
Cannot read the request file
Do not retrycurl: Failed to open requests.json
curl: option -d: error encountered when reading a file
curl: try 'curl --help' or 'curl --manual' for more informationThe file named after @ could not be opened. This one has no (26) in the message, only the exit code.
Why it happens
- A bulk call sends its list of requests as a JSON file with -d @requests.json, and the file is not in the folder you are in.
- A typo in the file name, or no permission to read it.
Check
Look for the file from where you run curl:
ls -l requests.jsonFix
- Run the command in the folder that holds the file, or give the full path: -d @/home/you/requests.json.
Retry? No: the same command fails the same way.
2.The server was not reached
curl tried to open a connection and could not, or did not trust what answered.
Could not resolve host
Fix firstcurl: (6) Could not resolve host: no-such-host.invalidThe name in the address has no IP address, or the machine has no working DNS.
Why it happens
- A typo in the host name of the API address.
- No network, or no DNS, in a container, a CI job, a VPN or a locked-down server.
- A name that only exists inside another network.
Check
Ask the system resolver, then try the site itself:
getent hosts curlshot.com
curl -sSI https://curlshot.comFix
- Correct the host name.
- Fix DNS in the environment: another resolver, a network flag on the container, or an allowed outbound route.
Retry? Only after the cause is fixed. Retrying only helps if the network was down for a moment.
Failed to connect
Fix firstcurl: (7) Failed to connect to 127.0.0.1 port 1 after 0 ms: Couldn't connect to serverThe name resolved, but nothing accepted the connection on that address and port.
Why it happens
- The wrong port, or a local server that is not running.
- A firewall or an outbound rule that blocks the connection.
- A proxy variable (https_proxy) that points at a proxy that is down. curl uses it without telling you.
Other wording
- Connection refused
- Connection timed out after N milliseconds, when a firewall drops the packets instead of refusing them
Check
List proxy variables, then watch the connection:
env | grep -i '^\(http\|https\|all\)_proxy'
curl -v https://curlshot.com -o /dev/nullFix
- Use the right port. The address of the API has no port in it, so the default for https:// is used.
- Unset or fix the proxy variable, or allow outbound HTTPS on port 443.
Retry? Only after the cause is fixed. curl does not retry a refused connection on its own, even with --retry, unless you add --retry-connrefused.
TLS handshake failed
Do not retrycurl: (35) OpenSSL/3.0.13: error:0A00010B:SSL routines::wrong version numberThe two sides could not agree on a secure connection.
Why it happens
- https:// aimed at a port that speaks plain HTTP. This is how a local mock server or a misconfigured proxy shows up.
- A very old TLS library, or a device on the path that interferes with the handshake.
Other wording
- SSL connect error
- Other TLS libraries print their own words for the same exit code.
Check
The first lines of the verbose output show where it stops:
curl -v https://curlshot.com -o /dev/null 2>&1 | head -20Fix
- Use http:// only for a local test server, and https:// for the real API.
- Update curl and its TLS library, or take the proxy out of the path to see if it is the cause.
Retry? No: the same command fails the same way.
Certificate not trusted
Do not retrycurl: (60) SSL certificate problem: self-signed certificate
More details here: https://curl.se/docs/sslcerts.html
curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the web page mentioned above.The server presented a certificate that curl does not trust, so it stopped before sending your request.
Why it happens
- A server with a self-signed certificate, such as a local test server.
- A company proxy that inspects TLS and signs with its own certificate that your machine does not know.
- An old or missing CA bundle, or a wrong system clock, which makes a valid certificate look expired.
Other wording
- unable to get local issuer certificate
- certificate has expired
Check
The system clock first, then the certificate chain:
date -u
curl -v https://curlshot.com -o /dev/null 2>&1 | grep -i 'issuer\|expire'Fix
- Point curl at the right CA file for this one call: --cacert company-ca.pem.
- Update the CA bundle of the machine, and set the clock.
- Do not add -k (--insecure). It turns verification off, and your access key travels in this request.
Retry? No: the same command fails the same way.
Why not -k for exit 60?
-k (--insecure) switches certificate checks off. The curl project advises against it even for development.[3] Your access key is part of every request, and without the check anyone on the path can read it.3.The answer was lost
The connection opened, then it was too slow, was cut, or ended early.
Operation timed out
Retry after a pausecurl: (28) Operation timed out after 2002 milliseconds with 0 bytes receivedA time limit ran out before the answer was complete.
Why it happens
- curl has no time limit of its own. The limit comes from --max-time, --connect-timeout, a library default or a wrapper script.
- A render takes longer than that limit. The API option timeout is 30 seconds unless you set it, and can go up to 90.
Other wording
- Connection timed out after N milliseconds, when it is the connect step that ran out of time
- Operation timed out after N milliseconds with M bytes received
Check
Time the whole call, and print the stage that took long:
curl -sS -o /dev/null -w 'connect=%{time_connect}s total=%{time_total}s\n' \
"https://curlshot.com/api/v1/screenshot?access_key=YOUR_ACCESS_KEY&url=https://example.com"Fix
- Give curl more time than the render can take: set --max-time to the API timeout plus a margin. 100 seconds covers the largest timeout of 90.
- For pages that are slow on purpose, start the render with async=true and collect the result later.
Retry? Yes, after a pause. curl --retry covers a timeout. Raise the limit first, or each retry times out again.
Empty reply
Retry after a pausecurl: (52) Empty reply from serverThe connection opened and then closed without a single byte of HTTP.
Why it happens
- An API error is always a JSON message with an HTTP status, so this did not come from the API. Something on the path closed the connection: a proxy, a gateway, a firewall, or a server that was restarting.
Check
Watch where the connection closes:
curl -v "https://curlshot.com/api/v1/screenshot?access_key=YOUR_ACCESS_KEY&url=https://example.com" -o /dev/nullFix
- Try again after a few seconds, with a pause that grows.
- If it repeats from every network, write to support with the time (UTC) and the command with the key removed.
Retry? Yes, after a pause. curl --retry does not retry this code by itself. Use a loop, or --retry-all-errors only if the call can never be a bad request.
Connection reset
Retry after a pausecurl: (56) Recv failure: Connection reset by peerThe other side, or a device between you and it, tore the connection down while curl was waiting.
Why it happens
- A proxy, VPN or firewall that resets long connections.
- A server restart. Both are the network layer, not an API error, which would arrive as JSON.
Other wording
- The wording follows the operating system, for example Failure when receiving data from the peer.
Check
Compare with another network, such as a phone hotspot, and with the same call from a different machine.
Fix
- Retry after a pause.
- If it only happens on one network, look at the proxy or VPN on it.
Retry? Yes, after a pause.
Transfer closed early
Retry after a pausecurl: (18) transfer closed with 100 bytes remaining to readThe server promised a body of a certain length and the connection ended before all of it arrived.
Why it happens
- The connection dropped in the middle of the image.
- In the lab run, curl left the 100 bytes it had received in the output file. That file is a broken picture that still has a .png name.
Other wording
- Older curl: Transferred a partial file
Check
A broken image has the wrong size, or the file tool cannot name it:
ls -l shot.png
file shot.pngFix
- Delete the file and ask again.
- Write to a temporary name and rename it only when curl exits 0. The script below does this.
Retry? Yes, after a pause. curl --retry does not retry this code unless you add --retry-all-errors.
4.An answer came, but not the picture
The server answered. The status, the file or the exit code says something other than "a screenshot".
HTTP error status
Retry after a pausecurl: (22) The requested URL returned error: 429The server answered with a status of 400 or higher. The API explains it in JSON.
Why it happens
- The request is wrong (400, 401, 402, 403, 404). The error_code in the JSON says which part.
- You are sending too fast or too many renders are running (429), or there is a short problem on the other side (500, 502, 503, 504).
Other wording
- Only appears with --fail or --fail-with-body. Without them, curl prints nothing and exits 0.
- Older curl: The requested URL returned error: 429 Too Many Requests
Check
Keep the body with --fail-with-body, then read the code:
curl -sS --fail-with-body -o answer.json \
"https://curlshot.com/api/v1/screenshot?access_key=YOUR_ACCESS_KEY&url=example.com"
cat answer.jsonFix
- Read error_code and error_message in the body. The errors page lists every code with its fix.
- Use --fail-with-body, not --fail. --fail throws the body away, which is the part that explains the problem.
- With --retry 3, curl retries 429 and 5xx answers and waits the number of seconds in Retry-After. In the lab run it waited 7 seconds for a Retry-After of 7.
Retry? Yes, after a pause. 429, 500, 502, 503 and 504: yes. 400 to 403 and 404: no.
Cannot write the file
Fix firstcurl: (23) Failure writing output to destinationcurl received the data and could not save it.
Why it happens
- The folder in -o does not exist.
- No permission to write there, or the disk is full.
Other wording
- Writing to a full disk (/dev/full in the lab) exited 23 as well.
Check
Folder, permissions, free space:
ls -ld output/
df -h .Fix
- Add --create-dirs and curl makes the missing folders. In the lab run this made newdir/x.png.
- Choose a folder you can write to, or free some space.
Retry? Only after the cause is fixed.
Exit 0, but the file is JSON
(no error message)
exit=0
http=400 type=application/json
shot.png: JSON text dataThis is not an error for curl. A 400 answer is still an answer, so curl saves it and exits 0.
Why it happens
- A call without --fail. The error message of the API is now in the file you named .png, and an image viewer says the file is damaged.
Check
Print the status and the type, then ask what the file is:
curl -sS -o shot.png -w 'http=%{http_code} type=%{content_type}\n' \
"https://curlshot.com/api/v1/screenshot?access_key=YOUR_ACCESS_KEY&url=https://example.com"
file shot.pngFix
- Add --fail-with-body so a status of 400 or more gives exit 22.
- Or check that the status is 200 and the type starts with image/, video/ or application/pdf before you keep the file.
A call that names its error
The four stages become four outcomes: a file, the message of the API, a network problem, or a mistake in the command. This script sends one request and ends in one of them. It was run against the same lab server for a 200, a 400, an empty reply, a refused connection and a misspelled scheme, and ended with exit codes 0, 22, 52, 7 and 1.
#!/usr/bin/env bash
# usage: ./shot.sh https://example.com page.png
api="https://curlshot.com/api/v1"
page="$1"
out="$2"
curl -sS --fail-with-body --max-time 100 --retry 3 \
-G "$api/screenshot" \
-H "X-Access-Key: $SCREENSHOT_ACCESS_KEY" \
--data-urlencode "url=$page" \
-o "$out.part"
code=$?
case $code in
0)
mv "$out.part" "$out" ;;
22)
echo "The API refused the request: $(head -c 300 "$out.part")" >&2
rm -f "$out.part" ;;
6|7|18|28|52|56)
echo "Network problem (curl $code). Try again in a minute." >&2
rm -f "$out.part" ;;
*)
echo "Fix the command (curl $code) before you retry." >&2
rm -f "$out.part" ;;
esac
exit $code- -sS
- Hides the progress meter and keeps the error message. Without -S a failed call prints nothing.
- --fail-with-body
- A status of 400 or more gives exit 22 and keeps the JSON, so the script can show it.
- --max-time 100
- More than the largest render timeout of 90 seconds. Lower it if you set a smaller timeout.
- --retry 3
- Retries timeouts and 429, 500, 502, 503 and 504, and waits for Retry-After. It does not retry 400 to 404, so a bad request is not repeated.
- -o "$out.part"
- The picture only gets its real name when curl exits 0. A cut-off download or a JSON error never looks like a screenshot.
- case $code
- Splits "fix the command", "try later" and "the API said no", the three groups of this page.
The errors of CurlShot itself come as JSON with a status of 400 or more, and a failed render does not use a screenshot from your quota. The errors page lists each error_code. A free account is enough to try it: see the plans.
How this was tested
On 30 October 2026, curl 8.5.0 (libcurl 8.5.0, OpenSSL 3.0.13) on Linux, with the flags -sS, against a small HTTP and HTTPS server on 127.0.0.1 that was started for the test and then stopped. The server was made to fail in each way: it closed the connection, reset it, cut the body short, answered slowly, answered 429 with a Retry-After, and presented a self-signed certificate. For DNS the test used a name under .invalid, which is reserved so that it never resolves.
The messages are copied from those runs, and so are the numbers in the text: the 100 bytes left behind by exit 18, the 7 seconds of waiting for a Retry-After of 7, and the silent exit 1. The meaning of each exit code is from the curl manual.[1]
What this test did not cover: the live API. The error messages of CurlShot are described on the errors page, not measured here. And other curl versions, other TLS libraries and Windows word some messages differently, which is why the finder also takes the number alone.
Questions people ask
Why does curl exit 0 when my screenshot call failed?
Because the server did answer. A status of 400 or 429 is still an answer, and by default curl saves any answer and exits 0. Add --fail-with-body to get exit 22 for a status of 400 or more and keep the JSON in the file, or check that the status is 200 and the content type starts with image/ before you keep the file. CurlShot sends errors as JSON with the content type application/json.
Which curl errors are safe to retry?
Retry 28 (timeout), 52 (empty reply), 56 (connection reset) and 18 (transfer closed early) after a pause, and 22 only when the status was 429 or 5xx. Do not retry 1, 3, 26, 35 or 60: the same command fails the same way. The option --retry 3 covers timeouts and the statuses 408, 429, 500, 502, 503 and 504, and it waits for Retry-After. It does not cover 52, 56 or 18.
Should I use -k to fix curl error 60?
No. The option -k (--insecure) makes curl skip the certificate check, so anyone on the path could read the request, and the request carries your access key. The curl project recommends against skipping verification, even for development. Point curl at the right CA file with --cacert, update the CA bundle, and check the clock.
What value should --max-time have for a screenshot call?
Higher than the render timeout. The timeout option of CurlShot is 30 seconds when you do not set it and 90 at most, so --max-time 100 fits every setting. curl has no time limit of its own, so a timeout (28) always comes from a flag, a wrapper or a library. For pages that need longer than you want to wait, start the render with async=true and collect it later.
How do I see the error message of the API with curl?
Use --fail-with-body and write the output to a file or the terminal. The body is JSON with error_code, error_message and documentation_url, and it is kept even though curl exits with 22. Plain --fail discards the body, which is the part that explains what went wrong. The errors page of CurlShot lists every error_code with its cause and fix.
Sources
- [1]curl project, libcurl-errors: error codes in libcurl. Checked .
- [2]curl project, curl manual page: --fail-with-body, --max-time, --retry, --insecure. Checked .
- [3]curl project, TLS Certificate Verification. Checked .
Read next
- Rosetta stoneWebsite screenshot code examples in 8 languagesThe shortest working code to save a full-page screenshot of a website in curl, Node.js, Python, PHP, Go, Ruby, Java and C#, side by side.
- PlaybookHow to screenshot a list of URLs in bulkScreenshot hundreds or thousands of URLs: a queue simulator that says how long it takes, a short Node.js script, and what fails at scale.
- Field guideWhy website screenshots look wrong, and the fixesA field guide to 11 ways a website screenshot goes wrong, from blank lazy images to cookie banners and cut-off pages, with the cause and the fix for each.