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

Confirm libcurl >= 7.26.0 (curl --version), since POP3 custom requests require it.

curl_easy_perform() failed: %s

Error message

curl_easy_perform() failed: %s

What it means

Printed at pop3-dele.c:66 when curl_easy_perform(curl) at line 62 fails for a POP3 DELE custom request. The handle is configured with username/password, CURLOPT_URL=pop3://pop.example.com/1, CURLOPT_CUSTOMREQUEST="DELE", and CURLOPT_NOBODY=1 because DELE returns no data. The example requires libcurl >= 7.26.0 for custom POP3 commands; the %s is curl_easy_strerror(result).

Source

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

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

    /* You can specify the message either in the URL or DELE command */
    curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com/1");

    /* Set the DELE command */
    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELE");

    /* Do not perform a transfer as DELE returns no data */
    curl_easy_setopt(curl, CURLOPT_NOBODY, 1L);

    /* Perform the custom request */
    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

Confirm libcurl >= 7.26.0 (curl --version), since POP3 custom requests require it.
Enable CURLOPT_VERBOSE to see the POP3 conversation, including the server's response to USER/PASS and to the DELE command.
Verify message '1' exists and has not already been deleted; LIST it before DELE.
Use pop3s:// or CURLOPT_USE_SSL=CURLUSESSL_ALL if the server mandates TLS.
Distinguish auth failure from DELE failure via the numeric CURLcode and react accordingly.

Example fix

// before
curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELE");
curl_easy_setopt(curl, CURLOPT_NOBODY, 1L);
result = curl_easy_perform(curl);
if(result != CURLE_OK)
  fprintf(stderr, "curl_easy_perform() failed: %s\n",
          curl_easy_strerror(result));

// after - require TLS and report the numeric code
curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL);
curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELE");
curl_easy_setopt(curl, CURLOPT_NOBODY, 1L);
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

/* DELE is irreversible: confirm the message ID exists before performing */
if(msg_id <= 0) { fprintf(stderr, "invalid message id\n"); return -1; }
/* Issue LIST/UIDL first and confirm msg_id is in the returned set */
curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "LIST");
if(!msg_id_exists(curl, msg_id)) { fprintf(stderr, "msg %ld not found\n", msg_id); return -1; }
/* only now set the DELE custom request */
curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELE");

Type guard

static int valid_msgid(long id) {
    return id > 0; /* POP3 message numbers are 1-based positive integers */
}

Try / catch

result = curl_easy_perform(curl);
if(result != CURLE_OK) {
    fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(result));
    /* A failed DELE may or may not have run server-side; re-STAT to learn true state. */
}

Prevention

DELE is destructive and irreversible: list/UIDL first to confirm the message number exists.
Track UIDs, not sequence numbers, so deletions are idempotent across sessions.
DELE is only finalized when QUIT completes - handle failures before QUIT carefully.
Enable CURLOPT_VERBOSE to see the server's DELE + QUIT responses.
Test against a non-production mailbox first; treat CURLE_QUOTE_ERROR as a bad command sequence.

When it happens

Trigger: Triggered when the POP3 server rejects the DELE (invalid message number, message already deleted, insufficient permissions), when authentication fails, when the connection to pop.example.com cannot be established, or when libcurl is older than 7.26.0 and does not support CURLOPT_CUSTOMREQUEST for POP3. Common codes are CURLE_LOGIN_DENIED, CURLE_QUOTE_ERROR, or CURLE_COULDNT_CONNECT.

Common situations: Message index '1' does not exist or was already DELEted in a previous run, wrong credentials, plain pop3:// blocked by the server's policy that requires TLS, or a too-old libcurl that ignores CURLOPT_CUSTOMREQUEST for POP3. Also seen when the example is repointed at a real mailbox whose numbering differs.

Related errors

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