Mbed TLS Common Error Troubleshooting

[中文]

The following are some common error logs in ESP-IDF’s Mbed TLS, their corresponding causes, and possible solutions.

Example: esp-tls: couldn’t get hostname for :drive.google.com: getaddrinfo() returns 202, addrinfo=0x0

The complete log for this issue is often:

E (83792) esp-tls: couldn't get hostname for :drive.google.com: getaddrinfo() returns 202, addrinfo=0x0
E (83792) esp-tls: Failed to open new connection
E (83792) transport_base: Failed to open a new connection
E (83802) HTTP_CLIENT: Connection failed, sock < 0

Error analysis:

  • getaddrinfo() failed to resolve, returning error code 202, indicating that drive.google.com could not be resolved, and addrinfo=0x0 indicates that getaddrinfo() did not return a valid IP address.

Possible reasons:

  • DNS resolution failed, possibly because the DNS server did not respond, or ESP did not receive this response.

Warning

If multiple Netif interfaces are used simultaneously, such as Wi-Fi and LTE, since lwIP cannot support each Netif having an independent DNS server domain, if the DNS server can only be used by a certain Netif interface, this error will also occur when the DNS is overwritten by other Netif interfaces.

Solution:

  • It is best to enable the DNS debug log of the lwIP layer, or further confirm the reason through wireless packet capture.

Note

  1. The method to enable the debug log of the lwIP layer can refer to this ESP-FAQ.

  2. The method of wireless packet capture can refer to Espressif Wireshark User Guide.

Example: esp-tls-mbedtls: mbedtls_ssl_handshake returned -0x7F00

mbedtls -0x7F00

The complete log for this issue is often:

E (3968) esp-tls-mbedtls: mbedtls_ssl_handshake returned -0x7F00
E (3968) esp-tls: Failed to open new connection
E (3968) TRANSPORT_BASE: Failed to open a new connection
E (3978) HTTP_CLIENT: Connection failed, sock < 0
E (3978) http_post: http post request failed: ESP_ERR_HTTP_CONNECT
I (3988) http_event_handler: HTTP_EVENT_DISCONNECTED
W (3998) http_event_handler: last esp error code: 0x801a, mbedtls failure: 0x2880

Error Analysis:

  • mbedtls_ssl_handshake returns error code -0x7F00. By querying Mbed TLS Error Codes, it can be found that the cause is MBEDTLS_ERR_SSL_ALLOC_FAILED. Insufficient ESP available memory leads to Mbed TLS memory allocation failure.

Solution:

  • Optimize ESP memory to ensure that the maximum free block of ESP is sufficient for allocation to Mbed TLS.

Such problems can often be referred to Mbed TLS Error Codes for some references. Common error codes are summarized as follows:

Common Mbed TLS Error Codes

Error Name

Error Code

Cause of Error

Solution

MBEDTLS_ERR_SSL_ALLOC_FAILED

-0x7F00

Memory allocation failed

Check memory usage, ensure sufficient available memory

MBEDTLS_ERR_X509_FATAL_ERROR

-0x3000

Certificate parsing failed

Check the certificate file, ensure the certificate format is correct

MBEDTLS_ERR_X509_CERT_VERIFY_FAILED

-0x2700

Certificate verification failed

Ensure the core CA certificate is valid and check the certificate chain

MBEDTLS_ERR_X509_BAD_INPUT_DATA

-0x2800

Invalid certificate input data

Ensure the provided certificate format is correct

MBEDTLS_ERR_SSL_CONN_EOF

-0x7280

Connection received EOF

Check the connection status, ensure the other end has not closed unexpectedly

MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET

-0x7B00

Received a new session ticket

Ensure the other end is configured to support session tickets

MBEDTLS_ERR_SSL_INTERNAL_ERROR

-0x6C00

Internal error

Ensure the Mbed TLS library is configured correctly and enable debug to view detailed logs

MBEDTLS_ERR_SSL_TIMEOUT

-0x6800

Operation timeout

Increase the timeout or check the network condition

MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY

-0x7880

The other end notifies the connection to close

Close the connection and re-establish the session

MBEDTLS_ERR_SSL_NO_CLIENT_CERTIFICATE

-0x7480

Client certificate required but not provided

Ensure the client has provided the correct certificate and configured two-way authentication

MBEDTLS_ERR_SSL_INVALID_RECORD

-0x7200

Invalid TLS record

Ensure the communication data is complete and reliable, check if the problem is caused by IN_CONTENT_LENGTH being too small (for example, is it 16 K). Also, confirm that the TLS protocol parameters configured by the other end are consistent with this end.

MBEDTLS_ERR_X509_FEATURE_UNAVAILABLE

-0x2080

Certificate feature unavailable

Ensure that the relevant features are enabled, such as configuring the corresponding options if support for a specific encryption algorithm is required

MBEDTLS_ERR_X509_INVALID_FORMAT

-0x2180

Invalid certificate format

Ensure that the certificate file is in the correct format, and try to use the PEM format as much as possible

In addition, ESP-IDF also encapsulates some Mbed TLS APIs and summarizes some ESP TLS return values, which can be referred to ESP TLS return values.