Guides

ESP32 TLS handshake failed: mbedTLS error codes and fixes

In short

An ESP32 TLS failure carries up to three numbers: an esp-tls error such as ESP_ERR_MBEDTLS_SSL_HANDSHAKE_FAILED, an mbedTLS code such as -0x2700, and X.509 verify flags. -0x2700 means the ESP32 rejected the server's certificate, and the flags say why. -0x7780 means the server ended the handshake, usually over your client certificate or key.

Updated · By · 12 min read · Markdown

An ESP32 TLS handshake fails for one of four reasons: the ESP32 rejected the server's certificate, the server rejected the ESP32, the network dropped the connection, or the chip ran out of memory. The mbedTLS code in the log line tells you which. This page maps every code an ESP32 MQTT or HTTPS client realistically hits to its cause and its fix.

Every code and constant here comes from the headers shipped with Arduino-ESP32 3.1.3 (ESP-IDF 5.3, mbedTLS 3.6.2), the stack the Paqett SDK builds on. The same values apply to any ESP-IDF 5.x project.

How do I read an ESP32 TLS error?

An ESP32 TLS failure reports up to four values: an esp_err_t from esp-tls, an mbedTLS error code, the X.509 verify flags and the socket errno. Read them in that order. The esp-tls error names the stage that failed, the mbedTLS code names the reason, and the flags explain a certificate rejection.

The familiar log line comes from esp-tls:

E (5321) esp-tls-mbedtls: mbedtls_ssl_handshake returned -0x2700
E (5322) esp-tls: Failed to open new connection
E (5323) transport_base: Failed to open a new connection
E (5330) mqtt_client: Error transport connect

mbedTLS error codes are negative 16-bit numbers. Many combine a high-level code with a low-level one: -0x21E2 is MBEDTLS_ERR_X509_INVALID_FORMAT (-0x2180) plus MBEDTLS_ERR_ASN1_UNEXPECTED_TAG (-0x0062). If a code is missing from the table below, subtract the low-level part (the bottom 7 bits) and look up both halves.

Warning: esp-tls stores the mbedTLS code as a positive number. When esp_tls_stack_err or the esp_tls_code from esp_tls_get_and_clear_last_error reads 0x2700, the mbedTLS error is -0x2700. Compare it with -MBEDTLS_ERR_X509_CERT_VERIFY_FAILED, not with the constant itself.

Find your error: ESP32 TLS error code table

Find the code from your log in the first column. The codes are listed as ESP-IDF prints them.

CodeConstantMeaningMost likely causeFix
-0x2700MBEDTLS_ERR_X509_CERT_VERIFY_FAILEDThe ESP32 rejected the server's certificateWrong CA, wrong hostname, or a date check with no clockDecode the verify flags (next section)
-0x7780MBEDTLS_ERR_SSL_FATAL_ALERT_MESSAGEThe server sent a fatal TLS alertThe server rejected your client certificate or key, or requires a protocol the ESP32 lacksSee "What does -0x7780 mean?"
-0x7280MBEDTLS_ERR_SSL_CONN_EOFThe server closed the TCP connection mid-handshakeA non-TLS port, a proxy or firewall closing the socket, or a server refusing without an alertCheck host and port, then the server's log
-0x0050MBEDTLS_ERR_NET_CONN_RESETThe socket was reset (ECONNRESET or EPIPE)The server or a middlebox reset the connectionCheck the server's log and the network path
-0x004CMBEDTLS_ERR_NET_RECV_FAILEDA socket read failed for another reasonWi-Fi dropped or the route went awayCheck errno and the Wi-Fi state
-0x7A00MBEDTLS_ERR_SSL_BAD_CERTIFICATEThe server's Certificate message could not be processedA malformed or unsupported server certificateInspect the server's chain with a desktop TLS client
-0x6E00MBEDTLS_ERR_SSL_HANDSHAKE_FAILURENegotiation failedNo cipher suite, curve or signature algorithm in commonCompare the server's TLS 1.2 settings with the ESP32's
-0x7100MBEDTLS_ERR_SSL_BAD_INPUT_DATAAn SSL function got invalid argumentsA configuration mistake, for example a hostname over 255 charactersCheck what you pass to the client config
-0x7F00MBEDTLS_ERR_SSL_ALLOC_FAILEDmbedTLS could not allocate memoryNot enough free heap for the TLS buffersMeasure the heap (see below)
-0x2880MBEDTLS_ERR_X509_ALLOC_FAILEDOut of memory while parsing a certificateLow heap, or a very large CA chain or bundleFree heap before connecting
-0x2180MBEDTLS_ERR_X509_INVALID_FORMATA certificate is not valid DER or PEMA truncated PEM string, or PEM passed with an explicit lengthPass PEM with its terminating NUL and length 0
-0x3D00MBEDTLS_ERR_PK_KEY_INVALID_FORMATThe private key could not be parsedNot a key, a corrupted key, or a certificate in the key fieldCheck the key PEM that reaches the client
-0x3C00MBEDTLS_ERR_PK_PASSWORD_REQUIREDThe key is encryptedA password-protected PEM keyStore the key unencrypted and protect it with NVS and flash encryption
-0x3F00MBEDTLS_ERR_PK_TYPE_MISMATCHThe key type does not fit the operationAn RSA key where an EC key is expected, or the reverseMake the key match the certificate
-0x6900MBEDTLS_ERR_SSL_WANT_READNo data yet: call againNormal on non-blocking socketsNot an error. esp-tls retries until its timeout
-0x6800MBEDTLS_ERR_SSL_TIMEOUTAn mbedTLS read timed outOnly with an mbedTLS read timeout configuredA connect timeout shows as ESP_ERR_ESP_TLS_CONNECTION_TIMEOUT instead

esp-tls errors (ESPERR_ESP_TLS*)

The esp-tls error names the stage that failed. esp_err_to_name() prints these names, because Arduino-ESP32 3.1.3 builds with CONFIG_ESP_ERR_TO_NAME_LOOKUP on.

ValueNameWhat failed
0x8001ESP_ERR_ESP_TLS_CANNOT_RESOLVE_HOSTNAMEDNS lookup of the host
0x8002ESP_ERR_ESP_TLS_CANNOT_CREATE_SOCKETCreating the socket
0x8004ESP_ERR_ESP_TLS_FAILED_CONNECT_TO_HOSTThe TCP connect; errno holds the reason, such as ECONNREFUSED
0x8006ESP_ERR_ESP_TLS_CONNECTION_TIMEOUTTCP connect or handshake did not finish within the timeout
0x8008ESP_ERR_ESP_TLS_TCP_CLOSED_FINThe server closed the connection cleanly while the client was reading
0x8015ESP_ERR_MBEDTLS_X509_CRT_PARSE_FAILEDParsing the CA or client certificate
0x8016ESP_ERR_MBEDTLS_SSL_CONF_OWN_CERT_FAILEDLoading the client certificate and key into mbedTLS
0x8017ESP_ERR_MBEDTLS_SSL_SETUP_FAILEDSSL setup, including "no server verification option set"
0x8019ESP_ERR_MBEDTLS_PK_PARSE_KEY_FAILEDParsing the client private key
0x801AESP_ERR_MBEDTLS_SSL_HANDSHAKE_FAILEDThe handshake itself; the mbedTLS code says why

When the esp-tls error is ESP_ERR_MBEDTLS_SSL_HANDSHAKE_FAILED, the TCP connection worked and the problem is TLS. When it is one of the ESP_ERR_ESP_TLS_* connect errors and the mbedTLS code is 0, the ESP32 never reached a TLS server.

Why does the ESP32 time out during the TLS handshake?

ESP_ERR_ESP_TLS_CONNECTION_TIMEOUT means the TCP connect, or the connect and handshake together, did not finish within the client's timeout. The timeout is network.timeout_ms in esp-mqtt and timeout_ms in esp_http_client. No mbedTLS code comes with it, because nothing failed: the server simply did not answer in time.

The common causes are a firewall that silently drops packets to the port, a service that accepts the TCP connection but never answers the TLS ClientHello, and a weak Wi-Fi link that loses packets during the handshake. Check the port first. Then raise the timeout to 10 to 15 seconds and see whether the error turns into a real one.

What does -0x2700 mean on an ESP32?

-0x2700 (MBEDTLS_ERR_X509_CERT_VERIFY_FAILED) means the ESP32 checked the server's certificate and rejected it. The verify flags hold the reason. esp-tls records them whenever a handshake fails and a CA, a global CA store or the certificate bundle is configured.

How do I decode the X.509 verify flags?

The verify flags are a bit mask: add up the bits that are set. 0x0C, for example, is MBEDTLS_X509_BADCERT_CN_MISMATCH (0x04) plus MBEDTLS_X509_BADCERT_NOT_TRUSTED (0x08). These are the certificate bits from mbedtls/x509.h:

BitConstantMeaningUsual cause on an ESP32
0x01MBEDTLS_X509_BADCERT_EXPIREDValidity period has endedExpired server certificate, or a clock set in the future
0x02MBEDTLS_X509_BADCERT_REVOKEDListed on a CRLNeeds a CRL; esp-tls configures none, so this does not appear
0x04MBEDTLS_X509_BADCERT_CN_MISMATCHName does not match the hostConnected by IP address or by a name the certificate does not carry
0x08MBEDTLS_X509_BADCERT_NOT_TRUSTEDChain does not end at a trusted CAWrong CA PEM, an old CA, or the server sends an incomplete chain
0x40MBEDTLS_X509_BADCERT_MISSINGNo certificateThe server sent none
0x80MBEDTLS_X509_BADCERT_SKIP_VERIFYVerification was skippedVerification turned off
0x0100MBEDTLS_X509_BADCERT_OTHEROther reasonSet by a custom verify callback
0x0200MBEDTLS_X509_BADCERT_FUTUREValidity has not startedClock behind the certificate's start date, typically 1970
0x0800MBEDTLS_X509_BADCERT_KEY_USAGEkeyUsage forbids this useWrong certificate profile on the server
0x1000MBEDTLS_X509_BADCERT_EXT_KEY_USAGEextendedKeyUsage forbids this useA client-only certificate installed on the server
0x2000MBEDTLS_X509_BADCERT_NS_CERT_TYPEnsCertType forbids this useLegacy Netscape extension on the server certificate
0x4000MBEDTLS_X509_BADCERT_BAD_MDUnacceptable signature hashSHA-1 signature; the default profile accepts SHA-256 and above
0x8000MBEDTLS_X509_BADCERT_BAD_PKUnacceptable signature algorithmKey algorithm not allowed by the profile
0x010000MBEDTLS_X509_BADCERT_BAD_KEYUnacceptable keyRSA under 2048 bits, or a curve the profile does not allow

The remaining bits (0x10, 0x20, 0x0400, 0x020000, 0x040000, 0x080000) describe CRLs and appear only when you load one.

mbedtls_x509_crt_verify_info() turns the flags into text, one line per bit. The snippet further down prints it.

Fixing NOT_TRUSTED and CN_MISMATCH

Most -0x2700 errors are NOT_TRUSTED, CN_MISMATCH or both:

  • NOT_TRUSTED on a private broker. Give the client the CA that signed the broker's certificate. On Paqett that is the ca_pem from provisioning, never the public certificate bundle: the broker's certificate chains to the device CA, not to a public root.
  • NOT_TRUSTED on a public HTTPS server. Attach the certificate bundle (crt_bundle_attach = esp_crt_bundle_attach). Arduino-ESP32 3.1.3 ships the full bundle.
  • CN_MISMATCH. Connect by the hostname in the certificate. mbedTLS checks the subjectAltName entries when the certificate has them, and the CN only when it has none. Connecting by IP address fails unless the certificate lists that address.

What does -0x7780 mean on an ESP32?

-0x7780 (MBEDTLS_ERR_SSL_FATAL_ALERT_MESSAGE) means the server sent a fatal TLS alert and ended the handshake. The ESP32 accepted everything up to that point. The verify flags are 0, and the reason lives on the server.

The usual causes for an ESP32 client:

  1. The server rejected the client certificate. It was issued by a CA the server does not trust, or the client sent none to a server that requires one.
  2. The private key does not match the certificate. esp-tls parses the key and the certificate separately and never checks that they pair. The mismatch only shows when the server fails to verify the handshake signature and sends an alert.
  3. No protocol in common. Arduino-ESP32 3.1.3 builds mbedTLS with TLS 1.2 only (CONFIG_MBEDTLS_SSL_PROTO_TLS1_3 is off). A server that accepts only TLS 1.3 ends the handshake with an alert.

The alert number is visible only in the server's log, or on the ESP32 with mbedTLS debug output, which the Arduino build leaves out (CONFIG_MBEDTLS_DEBUG off). Check the server side first.

How do I get the full error out of esp-mqtt?

esp-mqtt hands every failure to MQTT_EVENT_ERROR with an esp_mqtt_error_codes_t in event->error_handle. For a transport failure, error_type is MQTT_ERROR_TYPE_TCP_TRANSPORT and four fields carry the detail: esp_tls_last_esp_err, esp_tls_stack_err, esp_tls_cert_verify_flags and esp_transport_sock_errno. For a broker refusal after a good handshake, error_type is MQTT_ERROR_TYPE_CONNECTION_REFUSED and connect_return_code holds the CONNACK code.

#include <esp_err.h>
#include <esp_log.h>
#include <mbedtls/error.h>
#include <mbedtls/x509_crt.h>
#include <mqtt_client.h>

static const char* TAG = "app";

static void log_mqtt_error(const esp_mqtt_error_codes_t* ec) {
    if (!ec) return;
    if (ec->error_type == MQTT_ERROR_TYPE_CONNECTION_REFUSED) {
        // TLS succeeded; the broker refused the MQTT CONNECT.
        ESP_LOGE(TAG, "CONNACK refused, return code %d", (int)ec->connect_return_code);
        return;
    }
    if (ec->error_type != MQTT_ERROR_TYPE_TCP_TRANSPORT) {
        ESP_LOGE(TAG, "mqtt error type %d", (int)ec->error_type);
        return;
    }
    // esp-tls stores the mbedTLS code as a positive number: 0x2700 is -0x2700.
    const int tls = ec->esp_tls_stack_err;
    const uint32_t flags = (uint32_t)ec->esp_tls_cert_verify_flags;
    char text[100] = "";
    if (tls != 0) mbedtls_strerror(-tls, text, sizeof text);
    ESP_LOGE(TAG, "esp=%s tls=-0x%04x (%s) flags=0x%x errno=%d",
             esp_err_to_name(ec->esp_tls_last_esp_err), (unsigned)tls, text,
             (unsigned)flags, ec->esp_transport_sock_errno);
    if (flags != 0) {
        char info[256];
        mbedtls_x509_crt_verify_info(info, sizeof info, "  ! ", flags);
        ESP_LOGE(TAG, "certificate rejected:\n%s", info);
    }
}

// In your MQTT event handler:
//   case MQTT_EVENT_ERROR: log_mqtt_error(event->error_handle); break;

mbedtls_strerror prints the constant's description, because Arduino-ESP32 3.1.3 builds with CONFIG_MBEDTLS_ERROR_STRINGS on.

How do I get the TLS error from esp_http_client?

esp_http_client passes the esp-tls error handle as evt->data in HTTP_EVENT_ERROR, which fires when esp_http_client_open() or esp_http_client_perform() fails to connect. Read it with esp_tls_get_and_clear_last_error():

#include <esp_http_client.h>
#include <esp_log.h>
#include <esp_tls.h>

static esp_err_t on_http_event(esp_http_client_event_t* evt) {
    if (evt->event_id == HTTP_EVENT_ERROR && evt->data) {
        int tls = 0, flags = 0;
        const esp_err_t esp = esp_tls_get_and_clear_last_error(
            static_cast<esp_tls_error_handle_t>(evt->data), &tls, &flags);
        ESP_LOGE("https", "esp=%s tls=-0x%04x flags=0x%x errno=%d", esp_err_to_name(esp),
                 (unsigned)tls, (unsigned)flags, esp_http_client_get_errno(evt->client));
    }
    return ESP_OK;
}

// cfg.event_handler = on_http_event;

The call clears the stored error. Read it once, in the first handler that sees it.

How do I turn the ESP-IDF TLS logs back on?

Call esp_log_level_set() with ESP_LOG_ERROR or higher for the tags esp-tls, esp-tls-mbedtls, transport_base, mqtt_client and HTTP_CLIENT. The Paqett SDK sets all five to ESP_LOG_NONE at boot, because the stack logs every refused connection mid-line with its own output. Build with IPNODE_QUIET_IDF_LOGS=0 to keep them.

for (const char* tag : {"esp-tls", "esp-tls-mbedtls", "transport_base", "mqtt_client", "HTTP_CLIENT"})
    esp_log_level_set(tag, ESP_LOG_VERBOSE);

On Arduino-ESP32 3.1.3 this restores the error lines only. The prebuilt ESP-IDF libraries are compiled with CONFIG_LOG_MAXIMUM_LEVEL at ERROR, so the info and debug messages, such as "Failed to verify peer certificate!", are not in the binary at all. The error handle above carries the same information. In a plain ESP-IDF build, raise the default log level to Debug and esp-tls also prints the decoded verify flags.

Does the ESP32 need the correct time for TLS?

Only if mbedTLS checks certificate dates, which depends on CONFIG_MBEDTLS_HAVE_TIME_DATE. Arduino-ESP32 3.1.3 builds with it off for the ESP32-C6, so mbedTLS never sets the EXPIRED or FUTURE flags and the ESP32 connects with its clock at 1970. The same build also accepts an expired server certificate.

With the option on, the system clock starts at 1970 after boot, so every certificate looks not yet valid and verification fails with MBEDTLS_X509_BADCERT_FUTURE (0x0200). Sync the time with SNTP and wait for it before the first TLS connection.

How much heap does an ESP32 TLS connection need?

Espressif measured about 42,196 bytes of heap for its https_request example with server validation and default mbedTLS settings. Enabling dynamic TX/RX buffers brought that to about 22,013 bytes. Arduino-ESP32 3.1.3 sets CONFIG_MBEDTLS_SSL_MAX_CONTENT_LEN to 16384 for both directions, so plan for the default figure plus your own certificates.

What matters is the largest free block, not only the total. Log both right before connecting:

#include <esp_heap_caps.h>
#include <esp_system.h>

ESP_LOGI("heap", "free=%u min=%u largest=%u",
         (unsigned)esp_get_free_heap_size(), (unsigned)esp_get_minimum_free_heap_size(),
         (unsigned)heap_caps_get_largest_free_block(MALLOC_CAP_8BIT));

If the largest block falls short when -0x7F00 or -0x2880 appears, free memory first: destroy an old client before starting a new one, and release large buffers before you connect.

Why does my ESP32 mutual TLS connection fail?

Mutual TLS adds failures the ESP32 cannot see in its own verify flags, because the server is the one checking. Where the failure appears tells you what broke:

What you seeCauseFix
ESP_ERR_MBEDTLS_PK_PARSE_KEY_FAILED, before any network trafficThe key PEM is empty, truncated or encryptedCheck the key you load from storage
-0x7780 during the handshakeWrong key for the certificate, a certificate from another CA, or no certificate sentPair the key and certificate from one enrolment; use the certificate the server's CA issued
CONNACK return code 5, MQTT_CONNECTION_REFUSE_NOT_AUTHORIZEDThe handshake passed; the broker refused the identityThe certificate is revoked or not issued to this device
CONNACK return code 4 or 2Bad username, or identifier rejectedCheck what the broker derives from the certificate

On Paqett the CN of the certificate is the device id, and the broker takes the MQTT username and client id from it. A revoked certificate passes the TLS handshake and is then refused with not authorised. The broker also refuses with not authorised for a few seconds when it cannot check a certificate with the platform, because it fails closed. Back off and retry. Provisioning explains revocation and re-keying, and the mutual TLS guide shows the full client setup.

A key that does not match its certificate usually means a new key was generated while the old certificate stayed in storage. Delete the stored certificate whenever you generate a new key, then enrol again.

FAQ

Why does my ESP32 say "mbedtls_ssl_handshake returned -0x2700"?

The ESP32 rejected the server's certificate. Read esp_tls_cert_verify_flags from the MQTT error handle, or the flags from esp_tls_get_and_clear_last_error. A value of 0x08 means the CA you gave does not sign the server's certificate. 0x04 means the hostname does not match.

What is mbedTLS error -0x7780?

It is MBEDTLS_ERR_SSL_FATAL_ALERT_MESSAGE: the server sent a fatal alert and closed the handshake. With a client certificate it almost always means the server did not accept that certificate or its key. Look in the server's log for the alert reason.

Why do esp_tls_stack_err values look positive?

esp-tls stores the magnitude of the mbedTLS error. A value of 0x2700 stands for -0x2700. Print it as -0x%04x and compare it against the negated constant.

Can I skip certificate verification on the ESP32 to make the error go away?

Skipping verification lets anyone on the network impersonate your server and read the traffic, including anything the device sends after the handshake. ESP-IDF refuses a TLS client with no CA unless you enable an insecure option on purpose. Fix the CA or the hostname instead.

Why does the ESP32 connect over TLS and then get "not authorised"?

The TLS handshake succeeded, so the certificates are valid. The MQTT broker then refused the identity in the certificate at CONNECT, with CONNACK return code 5. On Paqett that means the certificate has been revoked, was not issued to this device, or could not be checked for a moment.

Sources