What causes "curl perform failed: %s " in curl/curl?

Read the verbose output printed just above the message to find the failing stage (DNS, TLS, connect).

curl perform failed: %s

Error message

curl perform failed: %s

What it means

Transfer error on the first request in the cookie-interface example: curl_easy_perform() to https://www.example.com/ (with CURLOPT_VERBOSE on and the cookie engine started via CURLOPT_COOKIEFILE "") returned non-CURLE_OK. The message prints the translated CURLcode. An identical guard exists at line 135 for the second perform.

Source

Thrown at docs/examples/cookie_interface.c:92

int main(void)
{
  CURL *curl;
  CURLcode result;

  result = curl_global_init(CURL_GLOBAL_ALL);
  if(result != CURLE_OK)
    return (int)result;

  curl = curl_easy_init();
  if(curl) {
    char nline[512];

    curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/");
    curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
    curl_easy_setopt(curl, CURLOPT_COOKIEFILE, ""); /* start cookie engine */
    result = curl_easy_perform(curl);
    if(result != CURLE_OK) {
      fprintf(stderr, "curl perform failed: %s\n", curl_easy_strerror(result));
      return 1;
    }

    print_cookies(curl);

    printf("Erasing curl's knowledge of cookies!\n");
    curl_easy_setopt(curl, CURLOPT_COOKIELIST, "ALL");

    print_cookies(curl);

    printf("-----------------------------------------------\n"
           "Setting a cookie \"PREF\" via cookie interface:\n");
    /* Netscape format cookie */
    snprintf(nline, sizeof(nline), "%s\t%s\t%s\t%s\t%.0f\t%s\t%s",
             ".example.com", "TRUE", "/", "FALSE",
             difftime(time(NULL) + 31337, (time_t)0),
             "PREF", "hello example, I like you!");
    result = curl_easy_setopt(curl, CURLOPT_COOKIELIST, nline);

View on GitHub (pinned to 527573490e)

Solutions

Read the verbose output printed just above the message to find the failing stage (DNS, TLS, connect).
If behind a proxy, set CURLOPT_PROXY (and CURLOPT_PROXYPORT/CURLOPT_PROXYTYPE as needed).
For TLS verification errors, update the CA bundle via CURLOPT_CAINFO or point to the system bundle.
Confirm reachability independently with `curl -v https://www.example.com/` from the same host.

Example fix

// before
curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/");
curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "");
result = curl_easy_perform(curl);
if(result != CURLE_OK)
  fprintf(stderr, "curl perform failed: %s\n", curl_easy_strerror(result));

// after (harden TLS + optional proxy so the first perform succeeds)
curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/");
curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "");
curl_easy_setopt(curl, CURLOPT_CAINFO, "/etc/ssl/certs/ca-bundle.crt");
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
if(getenv("HTTPS_PROXY"))
  curl_easy_setopt(curl, CURLOPT_PROXY, getenv("HTTPS_PROXY"));
result = curl_easy_perform(curl);
if(result != CURLE_OK)
  fprintf(stderr, "curl perform failed: %s\n", curl_easy_strerror(result));

Defensive patterns

Strategy: retry

Try / catch

int a;
for(a = 0; a < 3; ++a) {
    result = curl_easy_perform(curl);
    if(result == CURLE_OK) break;
    if(result != CURLE_COULDNT_CONNECT &&
       result != CURLE_OPERATION_TIMEDOUT &&
       result != CURLE_SSL_CONNECT_ERROR) {
        fprintf(stderr, "curl perform failed: %s\n", curl_easy_strerror(result));
        break;   /* non-transient: stop retrying */
    }
    usleep(200000 << a);   /* 200ms, 400ms, 800ms backoff */
}

Prevention

Enable the cookie engine with a writable CURLOPT_COOKIEFILE so session state survives retries.
Retry only idempotent GETs — the cookie-import flows in this example are safe to retry.
Set CURLOPT_CONNECTTIMEOUT so a dead host fails fast and the retry loop is not stuck.
After exhausting retries, call curl_easy_cleanup to release cookies and pooled connections.

When it happens

Trigger: curl_easy_perform(curl) at cookie_interface.c:90 fails because of a DNS/TLS/connect problem reaching www.example.com, a TLS backend issue, or proxy misconfiguration. Because CURLOPT_VERBOSE is 1L, detailed diagnostics are printed to stderr just before this message.

Common situations: Running offline or with no network egress; a corporate proxy not configured (CURLE_COULDNT_CONNECT); an outdated CA bundle causing CURLE_PEER_FAILED_VERIFICATION; a sandboxed environment blocking outbound HTTPS.

Related errors

AI-assisted analysis of curl/curl@527573490e (2026-08-01). Data as JSON: /data/errors/066eaa5b838e1bde.json. Report an issue: GitHub.