What causes "curl_easy_perform() failed: %s " in curl/curl?

Verify libcurl version >= 7.66.0 (curl --version) since CURLOPT_SASL_AUTHZID is required by this example.

curl_easy_perform() failed: %s

Error message

curl_easy_perform() failed: %s

What it means

Printed at pop3-authzid.c:66 when curl_easy_perform(curl) at line 62 fails. The handle is configured for a POP3 RETR of message 1 from pop3://pop.example.com/1 using CURLOPT_USERNAME/CURLOPT_PASSWORD, CURLOPT_SASL_AUTHZID='shared-mailbox', and CURLOPT_LOGIN_OPTIONS='AUTH=PLAIN'. The example requires libcurl >= 7.66.0 because CURLOPT_SASL_AUTHZID was added then; on older builds the option is silently ignored and auth fails.

Source

Thrown at docs/examples/pop3-authzid.c:66

    /* Set the username and password */
    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");

    /* Set the authorization identity (identity to act as) */
    curl_easy_setopt(curl, CURLOPT_SASL_AUTHZID, "shared-mailbox");

    /* Force PLAIN authentication */
    curl_easy_setopt(curl, CURLOPT_LOGIN_OPTIONS, "AUTH=PLAIN");

    /* This retrieves message 1 from the user's mailbox */
    curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com/1");

    /* Perform the retr */
    result = curl_easy_perform(curl);

    /* Check for errors */
    if(result != CURLE_OK)
      fprintf(stderr, "curl_easy_perform() failed: %s\n",
              curl_easy_strerror(result));

    /* Always cleanup */
    curl_easy_cleanup(curl);
  }

  curl_global_cleanup();

  return (int)result;
}

View on GitHub (pinned to 527573490e)

Solutions

Verify libcurl version >= 7.66.0 (curl --version) since CURLOPT_SASL_AUTHZID is required by this example.
Turn on CURLOPT_VERBOSE and confirm the server advertises SASL PLAIN and that the AUTHZID/username are sent correctly.
Validate credentials and the 'shared-mailbox' authzid against the POP3 server with an IMAP/POP3 client.
Use pop3s:// (implicit TLS) or set CURLOPT_USE_SSL=CURLUSESSL_ALL so PLAIN auth is permitted by the server policy.
Confirm message '1' exists; a missing message can also surface as a perform failure.

Example fix

// before
curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com/1");
result = curl_easy_perform(curl);
if(result != CURLE_OK)
  fprintf(stderr, "curl_easy_perform() failed: %s\n",
          curl_easy_strerror(result));

// after - require TLS for PLAIN auth and surface the numeric code
curl_easy_setopt(curl, CURLOPT_URL, "pop3s://pop.example.com/1");
curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL);
result = curl_easy_perform(curl);
if(result != CURLE_OK)
  fprintf(stderr, "curl_easy_perform() failed: %s (code %d)\n",
          curl_easy_strerror(result), (int)result);

Defensive patterns

Strategy: validation

Validate before calling

/* Pre-validate credentials, authzid, and SASL support before perform */
if(!username || !*username || !password || !*password) {
    fprintf(stderr, "missing POP3 credentials\n"); return -1;
}
if(!authzid || !*authzid) {
    fprintf(stderr, "missing SASL authzid\n"); return -1;
}
/* CURLOPT_SASL_AUTHZID needs libcurl >= 7.66.0 */
if(curl_version_info(CURLVERSION_NOW)->version_num < 0x074200) {
    fprintf(stderr, "libcurl too old for SASL_AUTHZID\n"); return -1;
}

Try / catch

result = curl_easy_perform(curl);
if(result == CURLE_LOGIN_DENIED) {
    fprintf(stderr, "auth rejected (bad user/pass/authzid) - do NOT retry\n");
} else if(result != CURLE_OK) {
    fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(result));
}

Prevention

Confirm the server actually advertises SASL PLAIN (enable CURLOPT_VERBOSE to see the exchange).
Validate username, password and authzid are non-empty before perform.
Require libcurl >= 7.66.0 for CURLOPT_SASL_AUTHZID (check version_num).
Use pop3s:// (TLS) so credentials are not sent in the clear.
Never retry CURLE_LOGIN_DENIED - it is a permanent credential/config error.

When it happens

Trigger: Triggered when the POP3 server rejects PLAIN auth (no shared mailbox, wrong credentials, AUTH=PLAIN not advertised), when the server does not exist or refuses the connection, or when libcurl is too old to honor CURLOPT_SASL_AUTHZID. The %s is curl_easy_strerror(result), commonly CURLE_LOGIN_DENIED or CURLE_COULDNT_CONNECT.

Common situations: Typo'd username/password/authzid, server not offering PLAIN (so AUTH=PLAIN cannot be negotiated), outdated libcurl predating 7.66.0 silently dropping the AUTHZID option, TLS not enabled so the server refuses PLAIN, or message index '1' not existing in the mailbox.

Related errors

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