Editing Troubleshooting of curl errors (section)

== List of curl errors ==
=== How to resolve Command Execution: Works in DOS/Terminal but Not in PHP ===
Often, commands that run perfectly when manually executed in DOS or the Windows terminal (like [https://conemu.github.io/ ConEmu]) might not produce the expected outcome when run through PHP. A common issue is the command not generating the anticipated file.

Example cURL command for Windows terminal
<pre>
curl "https://www.example.com/path/to/resource/" ^
-H "authority: www.example.com" ^
-H "accept: text/html" ^
--data-raw "PARAMS" --compressed > output.html
</pre>

Solution
* '''Single Continuous String in PHP''': In PHP, when executing a shell command, avoid using the caret (^) for multi-line commands<ref>[https://stackoverflow.com/questions/69068/split-long-commands-in-multiple-lines-through-windows-batch-file/21000752#21000752 Split long commands in multiple lines through Windows batch file - Stack Overflow]</ref>, which is typical in the Command Prompt. Instead, ensure the command is one continuous string.

* '''Unsupported curl Options''': If you encounter an error like "curl: option --compressed: the installed libcurl version doesn't support this", it's a clear indication to remove or adjust the problematic option in the curl command.

Revised cURL command for PHP
<pre>
curl "https://www.example.com/path/to/resource/" -H "authority: www.example.com" -H "accept: text/html" --data-raw "PARAMS" > output.html
</pre>

=== How to resolve cURL Binary Output Warning ===
When executing a cURL command, you might encounter this warning message:

<pre>
Warning: Binary output can mess up your terminal. Use "--output -" to tell
Warning: curl to output it to your terminal anyway, or consider "--output
Warning: <FILE>" to save to a file.
</pre>

To resolve this warning, append the {{kbd | key=<nowiki>--output</nowiki>}} flag to your cURL command:
* To save the output to a file: {{kbd | key=<nowiki>--output output.file</nowiki>}}
* To force output to terminal: {{kbd | key=<nowiki>--output -</nowiki>}}

Example:
<pre>
curl https://example.com/binary-file --output output.file
</pre>

=== How to resolve cURL error: HTTP/2 stream 0 was not closed cleanly: PROTOCOL_ERROR (err 1) ===
Workaround solution<ref>[https://stackoverflow.com/questions/56865217/php-curl-error-http-2-stream-0-was-not-closed-cleanly-protocol-error-err-1 PHP Curl error HTTP/2 stream 0 was not closed cleanly: PROTOCOL_ERROR (err 1) - Stack Overflow]</ref>: 
<pre>
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
</pre>

=== How to resolve cUrl error (3) bad range in URL position xx ===

'''Problem'''
When using curl to download URLs containing special characters (like `[]`), you may encounter this error:
<pre>
curl: (3) bad range in URL position 33
</pre>

'''Solution'''
Convert special characters to URL-encoded format:

<pre>
# Incorrect example
curl "https://example.com/api?param[0]=value"

# Correct example
curl "https://example.com/api?param%5B0%5D=value"
</pre>

Common URL encoding references:
* `[` becomes `%5B`
* `]` becomes `%5D`
* Space becomes `%20`

'''Explanation'''
* URL specifications require certain special characters to be encoded for use
* Characters like `[]` have special meanings in URLs and can cause parsing errors if used directly
* URL encoding ensures these special characters can be correctly transmitted and parsed

If you're unsure whether encoding is needed, you can use an online URL encoder tool for conversion e.g. [https://www.urlencoder.org/ URL Encode and Decode - Online].


=== How to trace cUrl error (6) Could not resolve host ===

This DNS resolution error indicates the hostname doesn't exist. Here are the 3 key debugging steps:

1. Verify the main domain exists
<pre>
curl -i https://example.com
</pre>

2. Check subdomain DNS resolution
<pre>
nslookup subdomain.example.com
</pre>

3. Test correct URL structure
<pre>
# Maybe it's a path instead of subdomain
curl -i "https://www.example.com/subdomain/..."

# Or try common subdomain alternatives  
nslookup www.example.com
nslookup api.example.com
</pre>

Conclusion: If you get {{kbd | key=NXDOMAIN}}, the subdomain doesn't exist - verify the correct URL from your source.

=== How to resolve cUrl error (#5): Unsupported proxy syntax ===
Condition: the username of [https://en.wikipedia.org/wiki/SOCKS socks5 proxy] contains @ symbol such as {{kbd | key=<nowiki>bob@email.com</nowiki>}}
<pre>
curl_setopt($ch, CURLOPT_PROXY, 'socks5://username:password@localhost:12345');
// result is ok

curl_setopt($ch, CURLOPT_PROXY, 'socks5://bob@email.com:password@localhost:12345');
// met cUrl error (#5): Unsupported proxy syntax
</pre>

Solution: Escape the special symbol<ref>[https://superuser.com/questions/937124/log-in-to-ftp-using-windows-explorer-with-in-the-username Log in to FTP using Windows Explorer with @ in the username - Super User]</ref> using [https://www.urlencoder.org/ URL Encode and Decode - Online] or [https://www.php.net/manual/en/function.urlencode.php urlencode] function
<pre>
curl_setopt($ch, CURLOPT_PROXY, 'socks5://bob%40email.com:password@localhost:12345');
// result is ok
</pre>

=== How to resolve cUrl error (#56): OpenSSL SSL_read: No error. ===
Condition: The curl vesion 7.67.0 on windows met problem. Result of [https://www.php.net/manual/en/function.curl-version.php curl_version] returned:
<pre>
version: Array
(
    [version_number] => 475904
    [age] => 5
    [features] => 2953117
    [ssl_version_number] => 0
    [version] => 7.67.0
    [host] => x86_64-pc-win32
    [ssl_version] => OpenSSL/1.1.1d
    [libz_version] => 1.2.11
)
</pre>

Solution: Use other version of [https://curl.haxx.se/windows/ curl command] or curl on [https://www.cygwin.com/ Cygwin] or [https://packagist.org/packages/curl/curl cURL class for PHP].

Related articles
* [https://github.com/curl/curl/issues/4982 cURL error 56: OpenSSL SSL_read: No error information · Issue #4982 · curl/curl]

=== How to resolve cURL error: SSL: no alternative certificate subject name matches target host name xxx ===
Walkaround solution<ref>[https://stackoverflow.com/questions/20842970/curl-fix-curl-51-ssl-error-no-alternative-certificate-subject-name-matches Curl: Fix CURL (51) SSL error: no alternative certificate subject name matches - Stack Overflow]</ref>:

<pre>
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
</pre>

=== How to resolve the error: error code: 1010 ===

Identifying the Issue
* While attempting to download a webpage content via the cURL command, I encountered an issue where the output displayed was "error code: 1010". To delve deeper, I reran the cURL command with verbose mode activated (using the {{kbd | key=<nowiki>-v</nowiki>}} flag). The headers revealed in this mode included:

<pre>
< report-to: {"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report\/v4?s=xxx"}],"group":"cf-nel","max_age":604800}
< nel: {"success_fraction":0,"report_to":"cf-nel","max_age":604800}
< server: cloudflare
</pre>

Proposed Solution
* Instead of relying on the cURL command, switching to a JavaScript-based crawler is recommended as a solution to this problem <ref>[https://www.zenrows.com/blog/cloudflare-error-1010#how-to-avoid Cloudflare Error 1010: What Is It and How to Avoid - ZenRows]</ref>.

=== How to resolve 400 Bad Request Errors:  UTF-8 Character Encoding Issues ===
'''Problem Analysis:'''

Example cURL command for macOS terminal with error:
<pre>
$ curl "https://api.search.brave.com/res/v1/web/search?q=\"XXX\"+公司簡介+產品+服務" \
 -H "Accept: application/json" \
 -H "Accept-Encoding: gzip" \
 -H "X-Subscription-Token: YOUR_API_KEY_HERE"

> <html><body><h1>400 Bad request</h1>
Your browser sent an invalid request.
</body></html>
</pre>

'''Solutions'''

Properly Handle URL Encoding: Chinese characters and special symbols need to be correctly URL-encoded to avoid 400 Bad Request errors (online tool: [https://www.urlencoder.org/ URL Encode and Decode - Online]):
* {{kbd | key=<nowiki>"XXX"</nowiki>}} → {{kbd | key=<nowiki>%22XXX%22</nowiki>}}
* {{kbd | key=<nowiki>公司簡介</nowiki>}} → {{kbd | key=<nowiki>%E5%85%AC%E5%8F%B8%E7%B0%A1%E4%BB%8B</nowiki>}}
* {{kbd | key=<nowiki>產品</nowiki>}} → {{kbd | key=<nowiki>%E7%94%A2%E5%93%81</nowiki>}}
* {{kbd | key=<nowiki>服務</nowiki>}} → {{kbd | key=<nowiki>%E6%9C%8D%E5%8B%99</nowiki>}}

'''Revised cURL Command:'''

<pre>
$ curl "https://api.search.brave.com/res/v1/web/search?q=%22XXX%22+%E5%85%AC%E5%8F%B8%E7%B0%A1%E4%BB%8B+%E7%94%A2%E5%93%81+%E6%9C%8D%E5%8B%99" \
 -H "Accept: application/json"  \
 -H "Accept-Encoding: gzip" \
 -H "X-Subscription-Token: YOUR_API_KEY_HERE"
</pre>

=== How to resolve Error 405 Method Not Allowed ===
When I tried to crawl the web resource but met the error message: "Error 405 Method Not Allowed"

Solution: Make sure using the correct HTTP request method<ref>[https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html HTTP/1.1: Method Definitions]</ref> e.g. {{kbd | key=GET}} or {{kbd | key=POST}} to access the web resource.

=== How to resolve Error 415 Unsupported Media Type ===
When I tried to POST JSON (as payload) but met the error message: "Error 415 Unsupported Media Type"

Solution: Set the cUrl with the header {{kbd | key=<nowiki>Content-Type: application/json</nowiki>}}<ref>[https://stackoverflow.com/questions/11087872/php-curl-post-returns-a-415-unsupported-media-type PHP cURL POST returns a 415 - Unsupported Media Type - Stack Overflow]</ref> Example syntax of cUrl command as following:

<pre>
curl -X POST --header "Content-Type: application/json" --data '{"user" : "your_user_name", "token" : "your_token"}' "https://example.com/"
</pre>

=== How to rseolve cURL returns binary data instead of html or json ===

* [https://stackoverflow.com/questions/28283822/curl-returns-binary-data-instead-of-html php - cURL returns binary data instead of html - Stack Overflow]
* [https://errerrors.blogspot.com/2020/06/resolve-curl-returns-binary-data-instead-of-html-or-json.html 解決 cUrl 下載的網頁或 JSON 看起來像是亂碼的問題]

=== How to resolve the downloaded file was empty ===
Error condition
* When I executed the Curl command {{kbd | key=<nowiki>curl -O https://path/to/plain_text.txt</nowiki>}}, but the downloaded file was empty.

Solution
* After I enabled [https://ec.haxx.se/usingcurl/usingcurl-verbose verbose] option, I found the HTTP status code {{kbd | key=HTTP/1.1 302 Moved Temporarily}}. I added the location ([https://curl.haxx.se/docs/manpage.html#-L -L]) parameter to resolve the downloaded file was empty: {{kbd | key=<nowiki>curl -L -O https://path/to/plain_text.txt</nowiki>}},

<pre>
The truncated result after executed the command: curl -v -O https://path/to/plain_text.txt

< HTTP/1.1 302 Moved Temporarily
< Server: nginx
< Date: Tue, 25 Aug 2020 03:45:13 GMT
< Content-Type: text/html
< Transfer-Encoding: chunked
< Connection: keep-alive
< Keep-Alive: timeout=60
< Location: /path/to/plain_text.txt
</pre>

=== How to resolve the error: no matches found ===
'''Error condition'''
* When I executed the Curl command {{kbd | key=<nowiki>curl http://website.test/http_status.php?case=500</nowiki>}}, but I met the error message: "zsh: no matches found: <nowiki>http://website.test/http_status.php?case=500</nowiki>"

'''Solution'''<ref>[https://medium.com/%E5%BD%BC%E5%BE%97%E6%BD%98%E7%9A%84-swift-ios-app-%E9%96%8B%E7%99%BC%E5%95%8F%E9%A1%8C%E8%A7%A3%E7%AD%94%E9%9B%86/%E7%82%BA%E4%BB%80%E9%BA%BC-mac-terminal-curl-%E6%8C%87%E4%BB%A4%E7%9A%84%E7%B6%B2%E5%9D%80%E9%80%9A%E5%B8%B8%E8%A6%81%E5%8A%A0%E9%9B%99%E5%BC%95%E8%99%9F-8c3e9227be34 為什麼 Mac terminal curl 指令的網址通常要加雙引號 - 彼得潘的 Swift iOS App 開發問題解答集 - Medium]</ref>
* Double quote the {{kbd | key=<nowiki>URL</nowiki>}} e.g. {{kbd | key=<nowiki>curl "http://website.test/http_status.php?case=500"</nowiki>}}

'''Explanation''' by Claude
<div class="toccolours mw-collapsible mw-collapsed" style="width:400px; overflow:auto;">
When you see a "no matches found" error in zsh (a type of shell), it's because the shell gets confused by special characters in your command. The main problem is the question mark (?) in the URL.

In a shell, some characters do special jobs:
* ? means "any one character"
* * means "any set of characters"
* [] is for grouping characters
* {} is for making lists of items

Here's what happens:
# When you run curl without quotes, the shell sees the ? and thinks "I need to find a file that matches this pattern"
# It looks in your current folder for matching files
# It can't find any files, so it shows the error

The fix is simple: put double quotes ("") around your URL. This tells the shell "just use these characters exactly as they are - don't try to do anything special with them." Now the ? goes straight to curl as part of the web address, instead of being used as a special character by the shell.

</div>

=== How to resolve the error: Remote file name has no length ===

Error message
<pre>
curl -O "https://website.com/?p=123"
curl: Remote file name has no length
curl: (23) Failed writing received data to disk/application
</pre>

Solution
<pre>
curl "https://website.com/?p=123" -o myfile.html 
</pre>

Explanation of solution
* When you encounter an error while downloading a file with `curl`, it may be because the URL does not include a file name, causing `curl` to be unable to determine the name to save the file under. The solution is to manually specify a file name using the `-o` option, for example, `curl -o myfile.html "https://website.com/?p=123"`. Additionally, make sure you have enough disk space and are in a directory where you have write permissions.

=== How to resolve zsh parse error near `&' ===
Error condition
<pre>
% curl -XPOST http://localhost:3000/ -H "Content-Type: application/json"  -d'{"url": "https://someweb.com/Today's_Biggest_Trends"}'
dquote>
</pre>

Solution: Escape the single quote {{kbd | key=<nowiki>'</nowiki>}} became {{kbd | key=<nowiki>''</nowiki>}} (repeat the single quote twice)
<pre>
% curl -XPOST http://localhost:3000/ -H "Content-Type: application/json"  -d'{"url": "https://someweb.com/Today''s_Biggest_Trends"}'
</pre>

Trivial Solution {{exclaim}} '''NOT WORK''': single quote {{kbd | key=<nowiki>'</nowiki>}} became {{kbd | key=<nowiki>\'</nowiki>}}
<pre>
% curl -XPOST http://localhost:3000/ -H "Content-Type: application/json"  -d'{"url": "https://someweb.com/Today\'s_Biggest_Trends"}'
dquote>
</pre>

=== How to resolve zsh Event Not Found Error ===
When executing a cURL command with JSON data in zsh shell, you might encounter this error message:

<pre>
> zsh: event not found: \
</pre>

This occurs because zsh interprets the exclamation mark (!) as a history expansion character, even when it appears inside double quotes.

To resolve this error, use one of these approaches:

'''Method 1: Use single quotes for JSON data'''
{{kbd | key=<nowiki>-d '{"message": "Hello '\''world'\'' & welcome!", "price": "$19.99"}'</nowiki>}}

'''Method 2: Escape the exclamation mark'''
{{kbd | key=<nowiki>-d "{\"message\": \"Hello 'world' & welcome\!\", \"price\": \"\$19.99\"}"</nowiki>}}

'''Method 3: Use heredoc with stdin'''
{{kbd | key=<nowiki>-d @- << 'EOF'</nowiki>}}

'''Method 4: Save JSON to file and reference it'''
{{kbd | key=<nowiki>-d @payload.json</nowiki>}}

'''Method 5: Disable history expansion temporarily'''<ref>[https://www.reddit.com/r/bash/comments/cl54to/not_sure_why_mac_is_saying_bash_event_not_found/?show=original not sure why mac is saying `-bash: !": event not found` when I try to simply echo a string containing a "!" : r/bash]</ref>
{{kbd | key=<nowiki>set +H</nowiki>}} (before the command)

Example with corrected syntax:

Using single quotes:
<pre>
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello '\''world'\'' & welcome!", "price": "$19.99"}' \
  -v \
  https://example.com/api/
</pre>

Using heredoc (recommended for complex JSON):
<pre>
curl -X POST \
  -H "Content-Type: application/json" \
  -d @- \
  -v \
  https://example.com/api/ << 'EOF'
{
  "message": "Hello 'world' & welcome!",
  "price": "$19.99",
  "special_chars": "!@#$%^&*()_+{}|:<>?[]\\;'\",./"
}
EOF
</pre>

Using external JSON file:
<pre>
curl -X POST \
  -H "Content-Type: application/json" \
  -d @payload.json \
  -v \
  https://example.com/api/
</pre>

Note: The heredoc approach is recommended for complex JSON as it avoids all shell interpretation issues and maintains readable formatting.

=== How to Suppress the Progress Meter ===
When executing the curl command, the typical output includes detailed information about the download and upload process as shown below:
<pre>
 % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 90141  100 90141    0     0  20029      0  0:00:04  0:00:04 --:--:-- 22012
</pre>

To suppress the progress meter of the curl command, you can use the {{kbd | key=<nowiki>-s</nowiki>}} (silent) option, which hides all output, or the {{kbd | key=<nowiki>-S</nowiki>}} (silent with error messages) option, which suppresses the progress meter but still displays error messages.
<pre>
curl -sS [URL]
</pre>

Alternatively, if you prefer to suppress all output including error messages, use the {{kbd | key=<nowiki>-s</nowiki>}} (silent) option alone:
<pre>
curl -s [URL]
</pre>


=== How to resolve cURL Illegal Filename Character Error ===
When executing a cURL command with illegal characters in the output filename, you might encounter this error message:

<pre>
curl -o $'example\ntest.html' http://example.com

Warning: Failed to open the file $'example\ntest.html': No such file or
Warning: directory
curl: (23) client returned ERROR on write of 1256 bytes
</pre>

To resolve this error, use valid filename characters in your {{kbd | key=<nowiki>-o</nowiki>}} or {{kbd | key=<nowiki>--output</nowiki>}} flag:
* Remove illegal characters like: {{kbd | key=<nowiki>< > : " | ? * \</nowiki>}} and control characters
* Avoid path separators: {{kbd | key=<nowiki>/</nowiki>}} (unless creating directories)
* Use safe characters: {{kbd | key=<nowiki>a-z A-Z 0-9 - _ .</nowiki>}}
* Create directories first if needed: {{kbd | key=<nowiki>mkdir -p directory</nowiki>}}

=== cURL JSON Payload Issues in Windows vs Mac/Linux Systems ===

'''1. Problem'''
Error encountered when executing the following cURL command on Windows:
<pre>
Invalid JSON payload received. Unknown name "": Root element must be a message.
</pre>

'''2. Solution'''
Windows system:
<pre>
curl -X POST -H "Content-Type: application/json" "API_URL" -d "{\"key\":\"value\"}"
</pre>

Mac/Linux system:
<pre>
curl -X POST -H "Content-Type: application/json" "API_URL" -d '{"key":"value"}'
</pre>

PHP code:
<pre>
$is_windows = strtoupper(substr(PHP_OS, 0, 3)) === 'WIN';
if ($is_windows) {
    $command = sprintf('-d "{\"key\":\"%s\"}"', $value);
} else {
    $command = sprintf("-d '%s'", $json_payload);
}
</pre>

'''3. Problem Description'''
* Root cause: Windows and Mac/Linux handle quotes in shell commands differently
* Windows: Requires double quotes and escaped internal quotes
* Mac/Linux: Can use single quotes to wrap the complete JSON string
* When using incorrect quote formatting, the JSON payload is parsed incorrectly, causing the API to return a format error message