Skip to content
Error dictionaryBy 9 min read

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.

  1. Nothing was sent

    curl stopped on your machine. The address, the shell or a file is wrong, and no packet left.

  2. The server was not reached

    curl tried to open a connection and could not, or did not trust what answered.

  3. The answer was lost

    The connection opened, then it was too slow, was cut, or ended early.

  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".

One rule covers most of it

If the message has a number in brackets, look up the number, because the wording changes between curl versions and TLS libraries and the number does not.[1] Exit 22 is the one where the answer is in the body, so keep it with --fail-with-body.[2]

1.Nothing was sent

curl stopped on your machine. The address, the shell or a file is wrong, and no packet left.

exit 1

Protocol not supported

Do not retry
What curl printed
curl: (1) Protocol "htp" not supported or disabled in libcurl

The 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:

Terminal
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.

exit 3

URL rejected: malformed input

Do not retry
What curl printed
curl: (3) URL rejected: Malformed input to a URL function

curl 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:

Terminal
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.

Fix curl: (3) URL using bad/illegal format

exit 3

Unmatched brace in URL

Do not retry
What curl printed
curl: (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.

Fix curl: (3) URL using bad/illegal format

exit 26

Cannot read the request file

Do not retry
What curl printed
curl: Failed to open requests.json
curl: option -d: error encountered when reading a file
curl: try 'curl --help' or 'curl --manual' for more information

The 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:

Terminal
ls -l requests.json

Fix

  • 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.

Bulk screenshots

2.The server was not reached

curl tried to open a connection and could not, or did not trust what answered.

exit 6

Could not resolve host

Fix first
What curl printed
curl: (6) Could not resolve host: no-such-host.invalid

The 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:

Terminal
getent hosts curlshot.com
curl -sSI https://curlshot.com

Fix

  • 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.

exit 7

Failed to connect

Fix first
What curl printed
curl: (7) Failed to connect to 127.0.0.1 port 1 after 0 ms: Couldn't connect to server

The 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:

Terminal
env | grep -i '^\(http\|https\|all\)_proxy'
curl -v https://curlshot.com -o /dev/null

Fix

  • 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.

exit 35

TLS handshake failed

Do not retry
What curl printed
curl: (35) OpenSSL/3.0.13: error:0A00010B:SSL routines::wrong version number

The 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:

Terminal
curl -v https://curlshot.com -o /dev/null 2>&1 | head -20

Fix

  • 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.

exit 60

Certificate not trusted

Do not retry
What curl printed
curl: (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:

Terminal
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?

The option -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.

exit 28

Operation timed out

Retry after a pause
What curl printed
curl: (28) Operation timed out after 2002 milliseconds with 0 bytes received

A 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:

Terminal
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.

Waiting and timing

exit 52

Empty reply

Retry after a pause
What curl printed
curl: (52) Empty reply from server

The 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:

Terminal
curl -v "https://curlshot.com/api/v1/screenshot?access_key=YOUR_ACCESS_KEY&url=https://example.com" -o /dev/null

Fix

  • 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.

exit 56

Connection reset

Retry after a pause
What curl printed
curl: (56) Recv failure: Connection reset by peer

The 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.

exit 18

Transfer closed early

Retry after a pause
What curl printed
curl: (18) transfer closed with 100 bytes remaining to read

The 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:

Terminal
ls -l shot.png
file shot.png

Fix

  • 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".

exit 22

HTTP error status

Retry after a pause
What curl printed
curl: (22) The requested URL returned error: 429

The 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:

Terminal
curl -sS --fail-with-body -o answer.json \
  "https://curlshot.com/api/v1/screenshot?access_key=YOUR_ACCESS_KEY&url=example.com"
cat answer.json

Fix

  • 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.

Errors

exit 23

Cannot write the file

Fix first
What curl printed
curl: (23) Failure writing output to destination

curl 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:

Terminal
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

Exit 0, but the file is JSON

What curl printed
(no error message)
exit=0
http=400 type=application/json
shot.png: JSON text data

This 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:

Terminal
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.png

Fix

  • 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.

How to tell success from failure

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.

shot.sh
#!/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.

Screenshot any page in one step

Paste an address into CurlShot and download the screenshot. A free account gives you 100 screenshots every month. No card needed.