# 15 curl errors on a screenshot call, with fixes

> 15 curl errors from real runs of a screenshot call: the exact message, what it means, how to check it and the fix. Paste yours to look it up.

Error dictionary by Serghei Pogor, founder of CurlShot (https://curlshot.com/about/serghei-pogor). Published 3 November 2026. Page for people: https://curlshot.com/blog/curl-errors-screenshot-api

When a curl call to a screenshot API fails, curl prints "curl: (N) message" and exits with the code N. Codes 1, 3 and 26 mean the command is wrong and nothing was sent. Codes 6, 7, 35 and 60 mean curl could not reach or trust the server. Codes 28, 52, 56 and 18 mean the answer was too slow, was cut off or never arrived. Code 22 means the server answered with an error status, and CurlShot then explains it in JSON. Exit code 0 does not prove you have a picture: without --fail, a 400 answer is saved to your .png file.

## Key facts

- The exit code is the stable part. The wording changes with the curl version and the TLS library, so look up the number first. This page covers 15 cases that were printed by a real run.
- 4 of them stop on your machine before anything is sent (exit 1, 3, 26). They cannot be fixed by a retry.
- CurlShot answers with JSON for every error of its own. An empty reply (52), a reset (56) or a cut-off body (18) came from the network on the way, so retry those after a pause.
- Use --fail-with-body, not --fail, and not nothing: it gives exit 22 for a status of 400 or more and keeps the JSON that explains the problem. Without it, curl exits 0 and saves the error as your image.
- Set --max-time above the render timeout. The timeout option is 30 seconds by default and 90 at most, so 100 seconds is safe for every setting.
- Do not use -k to get past exit 60. It turns off certificate checks, and your access key is in the request.

## Find your error

Paste the line curl printed, or only its number, on the page. This list is the same index: the exit code, the first words of the message, and the stage of the call where it breaks.

| Exit | Message starts with | Stage | Retry? |
| --- | --- | --- | --- |
| 1 | Protocol "htp" not supported or disabled in libcurl | Nothing was sent | No: the same command fails the same way |
| 3 | URL rejected: Malformed input to a URL function | Nothing was sent | No: the same command fails the same way |
| 3 | unmatched brace in URL position 34: | Nothing was sent | No: the same command fails the same way |
| 26 | Failed to open requests.json | Nothing was sent | No: the same command fails the same way |
| 6 | Could not resolve host: no-such-host.invalid | The server was not reached | Only after the cause is fixed |
| 7 | Failed to connect to 127.0.0.1 port 1 after 0 ms: Couldn't connect to server | The server was not reached | Only after the cause is fixed |
| 35 | OpenSSL/3.0.13: error:0A00010B:SSL routines::wrong version number | The server was not reached | No: the same command fails the same way |
| 60 | SSL certificate problem: self-signed certificate | The server was not reached | No: the same command fails the same way |
| 28 | Operation timed out after 2002 milliseconds with 0 bytes received | The answer was lost | Yes, after a pause |
| 52 | Empty reply from server | The answer was lost | Yes, after a pause |
| 56 | Recv failure: Connection reset by peer | The answer was lost | Yes, after a pause |
| 18 | transfer closed with 100 bytes remaining to read | The answer was lost | Yes, after a pause |
| 22 | The requested URL returned error: 429 | An answer came, but not the picture | Yes, after a pause |
| 23 | Failure writing output to destination | An answer came, but not the picture | Only after the cause is fixed |
| 0 | (no error message) | An answer came, but not the picture | Not an error for curl |

## 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

```text
curl: (1) Protocol "htp" not supported or disabled in libcurl
```

**What it means.** 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:

```bash
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

```text
curl: (3) URL rejected: Malformed input to a URL function
```

**What it means.** 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:

```bash
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.

More: [Fix curl: (3) URL using bad/illegal format](https://curlshot.com/docs/guides/curl-url-bad-illegal-format).

### Exit 3: Unmatched brace in URL

```text
curl: (3) unmatched brace in URL position 34:
http://127.0.0.1:18080/ok?filter={a
                                 ^
```

**What it means.** 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.

More: [Fix curl: (3) URL using bad/illegal format](https://curlshot.com/docs/guides/curl-url-bad-illegal-format).

### Exit 26: Cannot read the request file

```text
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
```

**What it means.** 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:

```bash
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.

More: [Bulk screenshots](https://curlshot.com/docs/bulk).

## 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

```text
curl: (6) Could not resolve host: no-such-host.invalid
```

**What it means.** 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:

```bash
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

```text
curl: (7) Failed to connect to 127.0.0.1 port 1 after 0 ms: Couldn't connect to server
```

**What it means.** 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:

```bash
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

```text
curl: (35) OpenSSL/3.0.13: error:0A00010B:SSL routines::wrong version number
```

**What it means.** 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:

```bash
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

```text
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.
```

**What it means.** 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:

```bash
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.

## The answer was lost

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

### Exit 28: Operation timed out

```text
curl: (28) Operation timed out after 2002 milliseconds with 0 bytes received
```

**What it means.** 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:

```bash
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.

More: [Waiting and timing](https://curlshot.com/docs/waiting).

### Exit 52: Empty reply

```text
curl: (52) Empty reply from server
```

**What it means.** 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:

```bash
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

```text
curl: (56) Recv failure: Connection reset by peer
```

**What it means.** 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

```text
curl: (18) transfer closed with 100 bytes remaining to read
```

**What it means.** 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:

```bash
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.

## 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

```text
curl: (22) The requested URL returned error: 429
```

**What it means.** 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:

```bash
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.

More: [Errors](https://curlshot.com/docs/errors).

### Exit 23: Cannot write the file

```text
curl: (23) Failure writing output to destination
```

**What it means.** 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:

```bash
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

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

**What it means.** 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:

```bash
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.

More: [How to tell success from failure](https://curlshot.com/docs/errors#how-to-tell-success-from-failure).

## A call that says which error it was

This script sends one screenshot request and ends in one of four ways: a file, the message of the API, a network problem, or a mistake in the command. 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.

```bash
#!/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
```

| Part | Why it is there |
| --- | --- |
| `-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. |

## How the messages were produced

Every message above was printed by curl 8.5.0 (libcurl 8.5.0, OpenSSL 3.0.13) on Linux on 30 October 2026, with -sS, against a small HTTP and HTTPS server on 127.0.0.1 that was started for the test and then stopped. DNS was tested with a name under .invalid, which is reserved and never resolves. The messages of the API itself were not part of this test: they are in [Errors](https://curlshot.com/docs/errors). Other curl versions and TLS libraries word some messages differently, so the exit code is the stable part. [1]

CurlShot answers a failed request with JSON and a status of 400 or more, and a failed render does not use a screenshot from your quota. See [Errors](https://curlshot.com/docs/errors) and [pricing](https://curlshot.com/pricing).

## Questions

### 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": https://curl.se/libcurl/c/libcurl-errors.html (checked 30 October 2026)
2. curl project, "curl manual page: --fail-with-body, --max-time, --retry, --insecure": https://curl.se/docs/manpage.html (checked 30 October 2026)
3. curl project, "TLS Certificate Verification": https://curl.se/docs/sslcerts.html (checked 30 October 2026)

## Go deeper

- [Screenshot API](https://curlshot.com/tools/screenshot-api)
- [Errors: every error code](https://curlshot.com/docs/errors)
- [Fix curl: (3) URL using bad/illegal format](https://curlshot.com/docs/guides/curl-url-bad-illegal-format)
- [Waiting and timing](https://curlshot.com/docs/waiting)
- [Pricing](https://curlshot.com/pricing)

## Read next

- [Website screenshot code examples in 8 languages](https://curlshot.com/blog/screenshot-code-examples.md): The 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.
- [How to screenshot a list of URLs in bulk](https://curlshot.com/blog/bulk-screenshots-list-of-urls.md): Screenshot hundreds or thousands of URLs: a queue simulator that says how long it takes, a short Node.js script, and what fails at scale.
- [Why website screenshots look wrong, and the fixes](https://curlshot.com/blog/why-website-screenshots-look-wrong.md): A 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.
