libcurl-errors.md (17897B)
1 --- 2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 SPDX-License-Identifier: curl 4 Title: libcurl-errors 5 Section: 3 6 Source: libcurl 7 See-also: 8 - CURLOPT_DEBUGFUNCTION (3) 9 - CURLOPT_ERRORBUFFER (3) 10 - CURLOPT_VERBOSE (3) 11 - curl_easy_strerror (3) 12 - curl_multi_strerror (3) 13 - curl_share_strerror (3) 14 - curl_url_strerror (3) 15 Protocol: 16 - All 17 Added-in: n/a 18 --- 19 20 # NAME 21 22 libcurl-errors - error codes in libcurl 23 24 # DESCRIPTION 25 26 This man page includes most, if not all, available error codes in libcurl. 27 Why they occur and possibly what you can do to fix the problem are also included. 28 29 # CURLcode 30 31 Almost all "easy" interface functions return a CURLcode error code. No matter 32 what, using the curl_easy_setopt(3) option CURLOPT_ERRORBUFFER(3) 33 is a good idea as it gives you a human readable error string that may offer 34 more details about the cause of the error than just the error code. 35 curl_easy_strerror(3) can be called to get an error string from a given 36 CURLcode number. 37 38 CURLcode is one of the following: 39 40 ## CURLE_OK (0) 41 42 All fine. Proceed as usual. 43 44 ## CURLE_UNSUPPORTED_PROTOCOL (1) 45 46 The URL you passed to libcurl used a protocol that this libcurl does not 47 support. The support might be a compile-time option that you did not use, it 48 can be a misspelled protocol string or just a protocol libcurl has no code 49 for. 50 51 ## CURLE_FAILED_INIT (2) 52 53 Early initialization code failed. This is likely to be an internal error or 54 problem, or a resource problem where something fundamental could not get done 55 at init time. 56 57 ## CURLE_URL_MALFORMAT (3) 58 59 The URL was not properly formatted. 60 61 ## CURLE_NOT_BUILT_IN (4) 62 63 A requested feature, protocol or option was not found built into this libcurl 64 due to a build-time decision. This means that a feature or option was not 65 enabled or explicitly disabled when libcurl was built and in order to get it 66 to function you have to get a rebuilt libcurl. 67 68 ## CURLE_COULDNT_RESOLVE_PROXY (5) 69 70 Could not resolve proxy. The given proxy host could not be resolved. 71 72 ## CURLE_COULDNT_RESOLVE_HOST (6) 73 74 Could not resolve host. The given remote host was not resolved. 75 76 ## CURLE_COULDNT_CONNECT (7) 77 78 Failed to connect() to host or proxy. 79 80 ## CURLE_WEIRD_SERVER_REPLY (8) 81 82 The server sent data libcurl could not parse. This error code was known as 83 *CURLE_FTP_WEIRD_SERVER_REPLY* before 7.51.0. 84 85 ## CURLE_REMOTE_ACCESS_DENIED (9) 86 87 We were denied access to the resource given in the URL. For FTP, this occurs 88 while trying to change to the remote directory. 89 90 ## CURLE_FTP_ACCEPT_FAILED (10) 91 92 While waiting for the server to connect back when an active FTP session is 93 used, an error code was sent over the control connection or similar. 94 95 ## CURLE_FTP_WEIRD_PASS_REPLY (11) 96 97 After having sent the FTP password to the server, libcurl expects a proper 98 reply. This error code indicates that an unexpected code was returned. 99 100 ## CURLE_FTP_ACCEPT_TIMEOUT (12) 101 102 During an active FTP session while waiting for the server to connect, the 103 CURLOPT_ACCEPTTIMEOUT_MS(3) (or the internal default) timeout expired. 104 105 ## CURLE_FTP_WEIRD_PASV_REPLY (13) 106 107 libcurl failed to get a sensible result back from the server as a response to 108 either a PASV or an EPSV command. The server is flawed. 109 110 ## CURLE_FTP_WEIRD_227_FORMAT (14) 111 112 FTP servers return a 227-line as a response to a PASV command. If libcurl 113 fails to parse that line, this return code is passed back. 114 115 ## CURLE_FTP_CANT_GET_HOST (15) 116 117 An internal failure to lookup the host used for the new connection. 118 119 ## CURLE_HTTP2 (16) 120 121 A problem was detected in the HTTP2 framing layer. This is somewhat generic 122 and can be one out of several problems, see the error buffer for details. 123 124 ## CURLE_FTP_COULDNT_SET_TYPE (17) 125 126 Received an error when trying to set the transfer mode to binary or ASCII. 127 128 ## CURLE_PARTIAL_FILE (18) 129 130 A file transfer was shorter or larger than expected. This happens when the 131 server first reports an expected transfer size, and then delivers data that 132 does not match the previously given size. 133 134 ## CURLE_FTP_COULDNT_RETR_FILE (19) 135 136 This was either a weird reply to a 'RETR' command or a zero byte transfer 137 complete. 138 139 ## Obsolete error (20) 140 141 Not used in modern versions. 142 143 ## CURLE_QUOTE_ERROR (21) 144 145 When sending custom "QUOTE" commands to the remote server, one of the commands 146 returned an error code that was 400 or higher (for FTP) or otherwise 147 indicated unsuccessful completion of the command. 148 149 ## CURLE_HTTP_RETURNED_ERROR (22) 150 151 This is returned if CURLOPT_FAILONERROR(3) is set TRUE and the HTTP server 152 returns an error code that is \>= 400. 153 154 ## CURLE_WRITE_ERROR (23) 155 156 An error occurred when writing received data to a local file, or an error was 157 returned to libcurl from a write callback. 158 159 ## Obsolete error (24) 160 161 Not used in modern versions. 162 163 ## CURLE_UPLOAD_FAILED (25) 164 165 Failed starting the upload. For FTP, the server typically denied the STOR 166 command. The error buffer usually contains the server's explanation for this. 167 168 ## CURLE_READ_ERROR (26) 169 170 There was a problem reading a local file or an error returned by the read 171 callback. 172 173 ## CURLE_OUT_OF_MEMORY (27) 174 175 A memory allocation request failed. This is serious badness and 176 things are severely screwed up if this ever occurs. 177 178 ## CURLE_OPERATION_TIMEDOUT (28) 179 180 Operation timeout. The specified time-out period was reached according to the 181 conditions. 182 183 ## Obsolete error (29) 184 185 Not used in modern versions. 186 187 ## CURLE_FTP_PORT_FAILED (30) 188 189 The FTP PORT command returned error. This mostly happens when you have not 190 specified a good enough address for libcurl to use. See 191 CURLOPT_FTPPORT(3). 192 193 ## CURLE_FTP_COULDNT_USE_REST (31) 194 195 The FTP REST command returned error. This should never happen if the server is 196 sane. 197 198 ## Obsolete error (32) 199 200 Not used in modern versions. 201 202 ## CURLE_RANGE_ERROR (33) 203 204 The server does not support or accept range requests. 205 206 ## Obsolete error (34) 207 208 Not used since 7.56.0. 209 210 ## CURLE_SSL_CONNECT_ERROR (35) 211 212 A problem occurred somewhere in the SSL/TLS handshake. You really want the 213 error buffer and read the message there as it pinpoints the problem slightly 214 more. Could be certificates (file formats, paths, permissions), passwords, and 215 others. 216 217 ## CURLE_BAD_DOWNLOAD_RESUME (36) 218 219 The download could not be resumed because the specified offset was out of the 220 file boundary. 221 222 ## CURLE_FILE_COULDNT_READ_FILE (37) 223 224 A file given with FILE:// could not be opened. Most likely because the file 225 path does not identify an existing file. Did you check file permissions? 226 227 ## CURLE_LDAP_CANNOT_BIND (38) 228 229 LDAP cannot bind. LDAP bind operation failed. 230 231 ## CURLE_LDAP_SEARCH_FAILED (39) 232 233 LDAP search failed. 234 235 ## Obsolete error (40) 236 237 Not used in modern versions. 238 239 ## Obsolete error (41) 240 241 Not used since 7.53.0. 242 243 ## CURLE_ABORTED_BY_CALLBACK (42) 244 245 Aborted by callback. A callback returned "abort" to libcurl. 246 247 ## CURLE_BAD_FUNCTION_ARGUMENT (43) 248 249 A function was called with a bad parameter. 250 251 ## Obsolete error (44) 252 253 Not used in modern versions. 254 255 ## CURLE_INTERFACE_FAILED (45) 256 257 Interface error. A specified outgoing interface could not be used. Set which 258 interface to use for outgoing connections' source IP address with 259 CURLOPT_INTERFACE(3). 260 261 ## Obsolete error (46) 262 263 Not used in modern versions. 264 265 ## CURLE_TOO_MANY_REDIRECTS (47) 266 267 Too many redirects. When following redirects, libcurl hit the maximum amount. 268 Set your limit with CURLOPT_MAXREDIRS(3). 269 270 ## CURLE_UNKNOWN_OPTION (48) 271 272 An option passed to libcurl is not recognized/known. Refer to the appropriate 273 documentation. This is most likely a problem in the program that uses 274 libcurl. The error buffer might contain more specific information about which 275 exact option it concerns. 276 277 ## CURLE_SETOPT_OPTION_SYNTAX (49) 278 279 An option passed in to a setopt was wrongly formatted. See error message for 280 details about what option. 281 282 ## Obsolete errors (50-51) 283 284 Not used in modern versions. 285 286 ## CURLE_GOT_NOTHING (52) 287 288 Nothing was returned from the server, and under the circumstances, getting 289 nothing is considered an error. 290 291 ## CURLE_SSL_ENGINE_NOTFOUND (53) 292 293 The specified crypto engine was not found. 294 295 ## CURLE_SSL_ENGINE_SETFAILED (54) 296 297 Failed setting the selected SSL crypto engine as default. 298 299 ## CURLE_SEND_ERROR (55) 300 301 Failed sending network data. 302 303 ## CURLE_RECV_ERROR (56) 304 305 Failure with receiving network data. 306 307 ## Obsolete error (57) 308 309 Not used in modern versions. 310 311 ## CURLE_SSL_CERTPROBLEM (58) 312 313 problem with the local client certificate. 314 315 ## CURLE_SSL_CIPHER (59) 316 317 Could not use specified cipher. 318 319 ## CURLE_PEER_FAILED_VERIFICATION (60) 320 321 The remote server's SSL certificate or SSH fingerprint was deemed not OK. 322 This error code has been unified with CURLE_SSL_CACERT since 7.62.0. Its 323 previous value was 51. 324 325 ## CURLE_BAD_CONTENT_ENCODING (61) 326 327 Unrecognized transfer encoding. 328 329 ## Obsolete error (62) 330 331 Not used in modern versions. 332 333 ## CURLE_FILESIZE_EXCEEDED (63) 334 335 Maximum file size exceeded. 336 337 ## CURLE_USE_SSL_FAILED (64) 338 339 Requested FTP SSL level failed. 340 341 ## CURLE_SEND_FAIL_REWIND (65) 342 343 When doing a send operation curl had to rewind the data to retransmit, but the 344 rewinding operation failed. 345 346 ## CURLE_SSL_ENGINE_INITFAILED (66) 347 348 Initiating the SSL Engine failed. 349 350 ## CURLE_LOGIN_DENIED (67) 351 352 The remote server denied curl to login (Added in 7.13.1) 353 354 ## CURLE_TFTP_NOTFOUND (68) 355 356 File not found on TFTP server. 357 358 ## CURLE_TFTP_PERM (69) 359 360 Permission problem on TFTP server. 361 362 ## CURLE_REMOTE_DISK_FULL (70) 363 364 Out of disk space on the server. 365 366 ## CURLE_TFTP_ILLEGAL (71) 367 368 Illegal TFTP operation. 369 370 ## CURLE_TFTP_UNKNOWNID (72) 371 372 Unknown TFTP transfer ID. 373 374 ## CURLE_REMOTE_FILE_EXISTS (73) 375 376 File already exists and is not overwritten. 377 378 ## CURLE_TFTP_NOSUCHUSER (74) 379 380 This error should never be returned by a properly functioning TFTP server. 381 382 ## Obsolete error (75-76) 383 384 Not used in modern versions. 385 386 ## CURLE_SSL_CACERT_BADFILE (77) 387 388 Problem with reading the SSL CA cert (path? access rights?) 389 390 ## CURLE_REMOTE_FILE_NOT_FOUND (78) 391 392 The resource referenced in the URL does not exist. 393 394 ## CURLE_SSH (79) 395 396 An unspecified error occurred during the SSH session. 397 398 ## CURLE_SSL_SHUTDOWN_FAILED (80) 399 400 Failed to shut down the SSL connection. 401 402 ## CURLE_AGAIN (81) 403 404 Socket is not ready for send/recv. Wait until it is ready and try again. This 405 return code is only returned from curl_easy_recv(3) and curl_easy_send(3) 406 (Added in 7.18.2) 407 408 ## CURLE_SSL_CRL_BADFILE (82) 409 410 Failed to load CRL file (Added in 7.19.0) 411 412 ## CURLE_SSL_ISSUER_ERROR (83) 413 414 Issuer check failed (Added in 7.19.0) 415 416 ## CURLE_FTP_PRET_FAILED (84) 417 418 The FTP server does not understand the PRET command at all or does not support 419 the given argument. Be careful when using CURLOPT_CUSTOMREQUEST(3), a 420 custom LIST command is sent with the PRET command before PASV as well. (Added 421 in 7.20.0) 422 423 ## CURLE_RTSP_CSEQ_ERROR (85) 424 425 Mismatch of RTSP CSeq numbers. 426 427 ## CURLE_RTSP_SESSION_ERROR (86) 428 429 Mismatch of RTSP Session Identifiers. 430 431 ## CURLE_FTP_BAD_FILE_LIST (87) 432 433 Unable to parse FTP file list (during FTP wildcard downloading). 434 435 ## CURLE_CHUNK_FAILED (88) 436 437 Chunk callback reported error. 438 439 ## CURLE_NO_CONNECTION_AVAILABLE (89) 440 441 (For internal use only, is never returned by libcurl) No connection available, 442 the session is queued. (added in 7.30.0) 443 444 ## CURLE_SSL_PINNEDPUBKEYNOTMATCH (90) 445 446 Failed to match the pinned key specified with CURLOPT_PINNEDPUBLICKEY(3). 447 448 ## CURLE_SSL_INVALIDCERTSTATUS (91) 449 450 Status returned failure when asked with CURLOPT_SSL_VERIFYSTATUS(3). 451 452 ## CURLE_HTTP2_STREAM (92) 453 454 Stream error in the HTTP/2 framing layer. 455 456 ## CURLE_RECURSIVE_API_CALL (93) 457 458 An API function was called from inside a callback. 459 460 ## CURLE_AUTH_ERROR (94) 461 462 An authentication function returned an error. 463 464 ## CURLE_HTTP3 (95) 465 466 A problem was detected in the HTTP/3 layer. This is somewhat generic and can 467 be one out of several problems, see the error buffer for details. 468 469 ## CURLE_QUIC_CONNECT_ERROR (96) 470 471 QUIC connection error. This error may be caused by an SSL library error. QUIC 472 is the protocol used for HTTP/3 transfers. 473 474 ## CURLE_PROXY (97) 475 476 Proxy handshake error. CURLINFO_PROXY_ERROR(3) provides extra details on 477 the specific problem. 478 479 ## CURLE_SSL_CLIENTCERT (98) 480 481 SSL Client Certificate required. 482 483 ## CURLE_UNRECOVERABLE_POLL (99) 484 485 An internal call to poll() or select() returned error that is not recoverable. 486 487 ## CURLE_TOO_LARGE (100) 488 489 A value or data field grew larger than allowed. 490 491 ## CURLE_ECH_REQUIRED (101)" 492 493 ECH was attempted but failed. 494 495 # CURLMcode 496 497 This is the generic return code used by functions in the libcurl multi 498 interface. Also consider curl_multi_strerror(3). 499 500 ## CURLM_CALL_MULTI_PERFORM (-1) 501 502 This is not really an error. It means you should call 503 curl_multi_perform(3) again without doing select() or similar in 504 between. Before version 7.20.0 (released on February 9 2010) this could be returned by 505 curl_multi_perform(3), but in later versions this return code is never 506 used. 507 508 ## CURLM_CALL_MULTI_SOCKET (-1) 509 510 An alias for *CURLM_CALL_MULTI_PERFORM*. Never returned by modern libcurl 511 versions. 512 (Added in 7.15.5) 513 514 ## CURLM_OK (0) 515 516 Things are fine. 517 518 ## CURLM_BAD_HANDLE (1) 519 520 The passed-in handle is not a valid *CURLM* handle. 521 522 ## CURLM_BAD_EASY_HANDLE (2) 523 524 An easy handle was not good/valid. It could mean that it is not an easy handle 525 at all, or possibly that the handle already is in use by this or another multi 526 handle. 527 528 ## CURLM_OUT_OF_MEMORY (3) 529 530 You are doomed. 531 532 ## CURLM_INTERNAL_ERROR (4) 533 534 This can only be returned if libcurl bugs. Please report it to us. 535 536 ## CURLM_BAD_SOCKET (5) 537 538 The passed-in socket is not a valid one that libcurl already knows about. 539 (Added in 7.15.4) 540 541 ## CURLM_UNKNOWN_OPTION (6) 542 543 curl_multi_setopt() with unsupported option 544 (Added in 7.15.4) 545 546 ## CURLM_ADDED_ALREADY (7) 547 548 An easy handle already added to a multi handle was attempted to get added a 549 second time. (Added in 7.32.1) 550 551 ## CURLM_RECURSIVE_API_CALL (8) 552 553 An API function was called from inside a callback. 554 555 ## CURLM_WAKEUP_FAILURE (9) 556 557 Wake up is unavailable or failed. 558 559 ## CURLM_BAD_FUNCTION_ARGUMENT (10) 560 561 A function was called with a bad parameter. 562 563 ## CURLM_ABORTED_BY_CALLBACK (11) 564 565 A multi handle callback returned error. 566 567 ## CURLM_UNRECOVERABLE_POLL (12) 568 569 An internal call to poll() or select() returned error that is not recoverable. 570 571 # CURLSHcode 572 573 The "share" interface returns a **CURLSHcode** to indicate when an error has 574 occurred. Also consider curl_share_strerror(3). 575 576 ## CURLSHE_OK (0) 577 578 All fine. Proceed as usual. 579 580 ## CURLSHE_BAD_OPTION (1) 581 582 An invalid option was passed to the function. 583 584 ## CURLSHE_IN_USE (2) 585 586 The share object is currently in use. 587 588 ## CURLSHE_INVALID (3) 589 590 An invalid share object was passed to the function. 591 592 ## CURLSHE_NOMEM (4) 593 594 Not enough memory was available. 595 (Added in 7.12.0) 596 597 ## CURLSHE_NOT_BUILT_IN (5) 598 599 The requested sharing could not be done because the library you use do not have 600 that particular feature enabled. (Added in 7.23.0) 601 602 # CURLUcode 603 604 The URL interface returns a *CURLUcode* to indicate when an error has 605 occurred. Also consider curl_url_strerror(3). 606 607 ## CURLUE_OK (0) 608 609 All fine. Proceed as usual. 610 611 ## CURLUE_BAD_HANDLE (1) 612 613 An invalid URL handle was passed as argument. 614 615 ## CURLUE_BAD_PARTPOINTER (2) 616 617 An invalid 'part' argument was passed as argument. 618 619 ## CURLUE_MALFORMED_INPUT (3) 620 621 A malformed input was passed to a URL API function. 622 623 ## CURLUE_BAD_PORT_NUMBER (4) 624 625 The port number was not a decimal number between 0 and 65535. 626 627 ## CURLUE_UNSUPPORTED_SCHEME (5) 628 629 This libcurl build does not support the given URL scheme. 630 631 ## CURLUE_URLDECODE (6) 632 633 URL decode error, most likely because of rubbish in the input. 634 635 ## CURLUE_OUT_OF_MEMORY (7) 636 637 A memory function failed. 638 639 ## CURLUE_USER_NOT_ALLOWED (8) 640 641 Credentials was passed in the URL when prohibited. 642 643 ## CURLUE_UNKNOWN_PART (9) 644 645 An unknown part ID was passed to a URL API function. 646 647 ## CURLUE_NO_SCHEME (10) 648 649 There is no scheme part in the URL. 650 651 ## CURLUE_NO_USER (11) 652 653 There is no user part in the URL. 654 655 ## CURLUE_NO_PASSWORD (12) 656 657 There is no password part in the URL. 658 659 ## CURLUE_NO_OPTIONS (13) 660 661 There is no options part in the URL. 662 663 ## CURLUE_NO_HOST (14) 664 665 There is no host part in the URL. 666 667 ## CURLUE_NO_PORT (15) 668 669 There is no port part in the URL. 670 671 ## CURLUE_NO_QUERY (16) 672 673 There is no query part in the URL. 674 675 ## CURLUE_NO_FRAGMENT (17) 676 677 There is no fragment part in the URL. 678 679 ## CURLUE_NO_ZONEID (18) 680 681 There is no zone id set in the URL. 682 683 ## CURLUE_BAD_FILE_URL (19) 684 685 The file:// URL is invalid. 686 687 ## CURLUE_BAD_FRAGMENT (20) 688 689 The fragment part of the URL contained bad or invalid characters. 690 691 ## CURLUE_BAD_HOSTNAME (21) 692 693 The hostname contained bad or invalid characters. 694 695 ## CURLUE_BAD_IPV6 (22) 696 697 The IPv6 address hostname contained bad or invalid characters. 698 699 ## CURLUE_BAD_LOGIN (23) 700 701 The login part of the URL contained bad or invalid characters. 702 703 ## CURLUE_BAD_PASSWORD (24) 704 705 The password part of the URL contained bad or invalid characters. 706 707 ## CURLUE_BAD_PATH (25) 708 709 The path part of the URL contained bad or invalid characters. 710 711 ## CURLUE_BAD_QUERY (26) 712 713 The query part of the URL contained bad or invalid characters. 714 715 ## CURLUE_BAD_SCHEME (27) 716 717 The scheme part of the URL contained bad or invalid characters. 718 719 ## CURLUE_BAD_SLASHES (28) 720 721 The URL contained an invalid number of slashes. 722 723 ## CURLUE_BAD_USER (29) 724 725 The user part of the URL contained bad or invalid characters. 726 727 ## CURLUE_LACKS_IDN (30) 728 729 libcurl lacks IDN support. 730 731 ## CURLUE_TOO_LARGE (31) 732 733 A value or data field is larger than allowed. 734 735 # CURLHcode 736 737 The header interface returns a *CURLHcode* to indicate when an error has 738 occurred. 739 740 ## CURLHE_OK (0) 741 742 All fine. Proceed as usual. 743 744 ## CURLHE_BADINDEX (1) 745 746 There is no header with the requested index. 747 748 ## CURLHE_MISSING (2) 749 750 No such header exists. 751 752 ## CURLHE_NOHEADERS (3) 753 754 No headers at all have been recorded. 755 756 ## CURLHE_NOREQUEST (4) 757 758 There was no such request number. 759 760 ## CURLHE_OUT_OF_MEMORY (5) 761 762 Out of resources 763 764 ## CURLHE_BAD_ARGUMENT (6) 765 766 One or more of the given arguments are bad. 767 768 ## CURLHE_NOT_BUILT_IN (7) 769 770 HTTP support or the header API has been disabled in the build.