Make TLS errors more descriptive

[jonatan-ivanov]

I got a TLS protocol version mismatch error for a link but according to sslscan, the site uses TLSv1.3 and there are not much details in the error message about what the exact issue is.

Command to repro the error:

 ❯ lychee <(echo 'https://duc.zevv.nl')
1/1 ━━━━━━━━━━━━━━━━━━━━ Finished extracting links
Issues found in 1 input. Find details below.

[/dev/fd/20]:
   [ERROR] https://duc.zevv.nl/ | Network error: TLS protocol version mismatch. The client and server cannot agree on a TLS version. This is often due to outdated system TLS libraries or the server TLS settings. (error sending request for url (https://duc.zevv.nl/)): TLS protocol version mismatch. The client and server cannot agree on a TLS version. This is often due to outdated system TLS libraries or the server TLS settings.

🔍 1 Total (in 0s) ✅ 0 OK 🚫 1 Error

sslscan says the supported protocols are:

SSLv2     disabled
SSLv3     disabled
TLSv1.0   disabled
TLSv1.1   disabled
TLSv1.2   disabled
TLSv1.3   enabled

Supported ciphers:

Preferred TLSv1.3  128 bits  TLS_AES_128_GCM_SHA256        Curve 25519 DHE 253
Accepted  TLSv1.3  256 bits  TLS_AES_256_GCM_SHA384        Curve 25519 DHE 253
Accepted  TLSv1.3  256 bits  TLS_CHACHA20_POLY1305_SHA256  Curve 25519 DHE 253

Setting

verbose = "trace"
format = "detailed"

doesn't give much extra info either, except the detailed format also says Unsupported in the summary.

[thomas-zahner]

This seems to be related to your specific system setup. lychee currently uses openssl which will differ from system to system.
On my system I get:

lychee <(echo 'https://duc.zevv.nl')
  1/1 ━━━━━━━━━━━━━━━━━━━━ Finished extracting links
🔍 1 Total (in 0s) ✅ 1 OK 🚫 0 Errors

What do you see when running curl https://duc.zevv.nl? I would suspect that curl also encounters issues. Also we intend to fully switch to rustls to mitigate such problems in the future, as we've had other people with similar issues. Related issues: #1920 & #1721

Could you try out if this PR resolves your issue?

[jonatan-ivanov]

I get that this is most likely environmental, my main issue is rather that the error message does not give me more details. Is the error message coming directly from openssl? Does lychee use the openssl executable or the library?

curl, sslscan, and my installation of openssl are fine but I'm using macOS, I have two openssl installations: one that is shipped with macOS (LibreSSL) and another one that I installed via homebrew (OpenSSL). The one I installed via homebrew takes precedence on my PATH, the built-in that I don't use fails (and resolves a different cert chain).

For the record, here's the curl output:

Click to reveal output of curl

 ❯ curl --verbose 'https://duc.zevv.nl'
* Host duc.zevv.nl:443 was resolved.
* IPv6: (none)
* IPv4: 45.142.232.22
*   Trying 45.142.232.22:443...
* ALPN: curl offers h2,http/1.1
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
* SSL Trust Anchors:
*   Native: Apple SecTrust
*   OpenSSL default paths (fallback)
* TLSv1.3 (IN), TLS handshake, Server hello (2):
* TLSv1.3 (IN), TLS change cipher, Change cipher spec (1):
* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
* TLSv1.3 (IN), TLS handshake, Certificate (11):
* TLSv1.3 (IN), TLS handshake, CERT verify (15):
* TLSv1.3 (IN), TLS handshake, Finished (20):
* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
* TLSv1.3 (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384 / x25519 / RSASSA-PSS
* ALPN: server accepted h2
* Server certificate:
*   subject: CN=duc.zevv.nl
*   start date: Oct  9 08:35:20 2025 GMT
*   expire date: Jan  7 08:35:19 2026 GMT
*   issuer: C=US; O=Let's Encrypt; CN=R12
*   Certificate level 0: Public key type RSA (2048/112 Bits/secBits), signed using sha256WithRSAEncryption
*   Certificate level 1: Public key type RSA (2048/112 Bits/secBits), signed using sha256WithRSAEncryption
*   Certificate level 2: Public key type RSA (4096/152 Bits/secBits), signed using sha256WithRSAEncryption
*   subjectAltName: "duc.zevv.nl" matches cert's "duc.zevv.nl"
* SSL certificate verified via OpenSSL.
* Established connection to duc.zevv.nl (45.142.232.22 port 443) from 192.168.0.102 port 54607
* using HTTP/2
* [HTTP/2] [1] OPENED stream for https://duc.zevv.nl/
* [HTTP/2] [1] [:method: GET]
* [HTTP/2] [1] [:scheme: https]
* [HTTP/2] [1] [:authority: duc.zevv.nl]
* [HTTP/2] [1] [:path: /]
* [HTTP/2] [1] [user-agent: curl/8.17.0]
* [HTTP/2] [1] [accept: */*]
> GET / HTTP/2
> Host: duc.zevv.nl
> User-Agent: curl/8.17.0
> Accept: */*
>
* Request completely sent off
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
< HTTP/2 200
[...]

Homebrew installed openssl:

 ❯ openssl version
OpenSSL 3.6.0 1 Oct 2025 (Library: OpenSSL 3.6.0 1 Oct 2025)

Click to reveal output of openssl

 ❯ openssl s_client -connect 'duc.zevv.nl:443' <<< 'GET /'
Connecting to 45.142.232.22
CONNECTED(00000005)
depth=2 C=US, O=Internet Security Research Group, CN=ISRG Root X1
verify return:1
depth=1 C=US, O=Let's Encrypt, CN=R12
verify return:1
depth=0 CN=duc.zevv.nl
verify return:1
---
Certificate chain
 0 s:CN=duc.zevv.nl
   i:C=US, O=Let's Encrypt, CN=R12
   a:PKEY: RSA, 2048 (bit); sigalg: sha256WithRSAEncryption
   v:NotBefore: Oct  9 08:35:20 2025 GMT; NotAfter: Jan  7 08:35:19 2026 GMT
 1 s:C=US, O=Let's Encrypt, CN=R12
   i:C=US, O=Internet Security Research Group, CN=ISRG Root X1
   a:PKEY: RSA, 2048 (bit); sigalg: sha256WithRSAEncryption
   v:NotBefore: Mar 13 00:00:00 2024 GMT; NotAfter: Mar 12 23:59:59 2027 GMT
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIE8jCCA9qgAwIBAgISBjF2+6jdvLvp1NZC1SkfuFglMA0GCSqGSIb3DQEBCwUA
MDMxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQwwCgYDVQQD
EwNSMTIwHhcNMjUxMDA5MDgzNTIwWhcNMjYwMTA3MDgzNTE5WjAWMRQwEgYDVQQD
EwtkdWMuemV2di5ubDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKCZ
xXOY9baOXjB9CgBNblbGqrT22WPoXmPciuXcFOQzOgDIRQ0OXzP3xSRqWL0imPG9
mw4X0EhmDlPf3LL3JIBtklqI6wulQ7GUdYjaVXQ0ZkOvthtWgAPN6mqXJ3vd4p4b
f3X/wRLp35fR9Aw4aVtziHCOfUPzDIttr3eqKzNn+s/QdtpD0eAyji2nkTkgSdyh
3rBoGLVEeQEN/4qojVZHRT2jFbA+s2LRtqnfwzW60rQpdH3fAsOy68nM3bZV6eQ5
wWL+AuzIKxwo64cNFKTNcUTMDD75owtkiyvgg2mBjEtBrpeimJQ9CMhfJDTHJNK3
6V9cUxm0DHiXUToyBLcCAwEAAaOCAhswggIXMA4GA1UdDwEB/wQEAwIFoDAdBgNV
HSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwDAYDVR0TAQH/BAIwADAdBgNVHQ4E
FgQUC3T/p91pLDKg+mLK6aKpJ+Gf+MswHwYDVR0jBBgwFoAUALUp8i2ObzHom0yt
eD763OkM0dIwMwYIKwYBBQUHAQEEJzAlMCMGCCsGAQUFBzAChhdodHRwOi8vcjEy
LmkubGVuY3Iub3JnLzAWBgNVHREEDzANggtkdWMuemV2di5ubDATBgNVHSAEDDAK
MAgGBmeBDAECATAuBgNVHR8EJzAlMCOgIaAfhh1odHRwOi8vcjEyLmMubGVuY3Iu
b3JnLzM4LmNybDCCAQQGCisGAQQB1nkCBAIEgfUEgfIA8AB1AGQRxGykEuyniRyi
Ai4AvKtPKAfUHjUnq+r+1QPJfc3wAAABmchR1JoAAAQDAEYwRAIgEP6aoAOefPNE
uPhX+wKymByqRnPTLeazpF6iJUka/PACICNidwl9w94lPEOYNA4Z/iFIFQiZLOrN
twLE/Ou1cFBjAHcAlpdkv1VYl633Q4doNwhCd+nwOtX2pPM2bkakPw/KqcYAAAGZ
yFHUxAAABAMASDBGAiEAm6vVIWeZlAZkjvM2cXyUIysyrsOg8AUa+otR0ATHvWoC
IQCI4KuA7Sx52haFSeTObC/owG8BxbO79ZPD8slgGw5S2TANBgkqhkiG9w0BAQsF
AAOCAQEAms5/3wSczqdY5azWZCya1mXSxQrR+4uYtbVzs7DlvEmHLGJLq4CoYCfc
I9B6JvQrk1ic8RWE0ea+zz3L1gGkaVYNKf+3bIVaUVRcmHcPWLyW4vuZRqSlEIcY
rN9JGUXlHAOta0ww60wogp9bFnjZ/CcVBtgum8Pi+fHrKJumhHnDdVrOYYD7TwOY
NBMbPujXRnz4vLli1Nbs+ongNN5J586Lw0XISCg4KMyd51UbVvi6T1oUnPE3tlVE
uQLcPUKgBVzVdb5OV+7eTFjJS09YZ2nXmN3NVsXPiR7MvGwo6CeoeiVgPsiVkOO4
J8p5EhUPeGhYG7lJY4Pr0r/B2hX0WA==
-----END CERTIFICATE-----
subject=CN=duc.zevv.nl
issuer=C=US, O=Let's Encrypt, CN=R12
---
No client certificate CA names sent
Peer signing digest: SHA256
Peer signature type: rsa_pss_rsae_sha256
Peer Temp Key: X25519, 253 bits
---
SSL handshake has read 3121 bytes and written 1622 bytes
Verification: OK
---
New, TLSv1.3, Cipher is TLS_AES_256_GCM_SHA384
Protocol: TLSv1.3
Server public key is 2048 bit
This TLS version forbids renegotiation.
Compression: NONE
Expansion: NONE
No ALPN negotiated
Early data was not sent
Verify return code: 0 (ok)
---
DONE

macOS "built-in" openssl:

 ❯ /usr/bin/openssl version
LibreSSL 3.3.6

Click to reveal output of "built-in" openssl

 ❯ /usr/bin/openssl s_client -connect 'duc.zevv.nl:443' <<< 'GET /'
CONNECTED(00000005)
depth=0 CN = bearcat.nl
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 CN = bearcat.nl
verify error:num=21:unable to verify the first certificate
verify return:1
write W BLOCK
---
Certificate chain
 0 s:/CN=bearcat.nl
   i:/C=US/O=Let's Encrypt/CN=R3
 1 s:/C=US/O=Let's Encrypt/CN=R3
   i:/C=US/O=Internet Security Research Group/CN=ISRG Root X1
 2 s:/C=US/O=Internet Security Research Group/CN=ISRG Root X1
   i:/O=Digital Signature Trust Co./CN=DST Root CA X3
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIE8DCCA9igAwIBAgISAyJFEOW4eLsWNunJovKH9zxuMA0GCSqGSIb3DQEBCwUA
MDIxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQswCQYDVQQD
EwJSMzAeFw0yMzA3MDYwNDEyMDBaFw0yMzEwMDQwNDExNTlaMBUxEzARBgNVBAMT
CmJlYXJjYXQubmwwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDJ+dZ7
VOW4X/8Esqyp6Fxg3o9tAaQrRN1lbXkpI5TVpyGkk48NShfWBk2v64wNEF8aDHzz
V3tnczlb9k8V+1BbgDX0F0a6Huq3WtNFdUrzx314GqWvdooiZGxy3m+SL44wmdVY
H+4bL9W3IZCQsVZO37KCbraeY+bfWQ3Un62dsnWY1n8R29ZygwmFnKdNNcJwnnGt
1ZijLqVfnXgcdejFDNrpBwK6vcI0svfjJtMmqkc0w4bZU56JxkauI0KIY+o+Amew
jn3FqQI/xwtNZTzs83bmIzLDyQEARj9k8pMgarnQL+pbIlig84HiEBBA7v3sw1p1
CG5DIP67Ww8mb8t9AgMBAAGjggIbMIICFzAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0l
BBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYE
FF7+xSpPgp+JziMkRZCZOuO1ETL3MB8GA1UdIwQYMBaAFBQusxe3WFbLrlAJQOYf
r52LFMLGMFUGCCsGAQUFBwEBBEkwRzAhBggrBgEFBQcwAYYVaHR0cDovL3IzLm8u
bGVuY3Iub3JnMCIGCCsGAQUFBzAChhZodHRwOi8vcjMuaS5sZW5jci5vcmcvMCUG
A1UdEQQeMByCCmJlYXJjYXQubmyCDnd3dy5iZWFyY2F0Lm5sMBMGA1UdIAQMMAow
CAYGZ4EMAQIBMIIBAwYKKwYBBAHWeQIEAgSB9ASB8QDvAHYAtz77JN+cTbp18jnF
ulj0bF38Qs96nzXEnh0JgSXttJkAAAGJKZ1IWwAABAMARzBFAiEAoTICrXTU5fT4
xYcyf97hYlHYwduVG6cflt79ll8Rz1kCIH++/MO51s4AazGbvYdf8COG8vdyMu3s
eftDpOV8d503AHUArfe++nz/EMiLnT2cHj4YarRnKV3PsQwkyoWGNOvcgooAAAGJ
KZ1IhwAABAMARjBEAiAGtQn2y3kY1eR82Qq8V/54abmaUkoKx3uu5ngfEwuTFQIg
W7rtGL/Rn0G3iRAg1Oq2e1keZ/5k0paXpp0FVTZLkFUwDQYJKoZIhvcNAQELBQAD
ggEBAGsqjVF6NCvyFy0MF6uSIZFf5XpVT+q93QCiP26hYGCd0srbLDz39ZhB7QEP
+HOlixobSiIJTcc2oHy7IRmddzf0TvSmczGZqduz1LKhH+YSiWF8UO5YQrpEHwW7
8t8TUQ9lehTwsd3Rj7MsYL3FJYlz2lqeX0S4XnKXrF9HcRNYd3aaN74zdsqJQz+d
lG+7pXP+syFaMOE58BxaMcX0rOVDoLLIZHn8h6e5n62UK7iBlCGkAd4iEjFbGMdc
84TrwBWN4OnJOsNJzoKYp/DajfuwFJizYZKs6s4qmJntLM4Uq+SV0hAZtS2ktrl/
D19ersUUR6fE6WORoExR5ZX9vG4=
-----END CERTIFICATE-----
subject=/CN=bearcat.nl
issuer=/C=US/O=Let's Encrypt/CN=R3
---
No client certificate CA names sent
Server Temp Key: ECDH, X25519, 253 bits
---
SSL handshake has read 4504 bytes and written 351 bytes
---
New, TLSv1/SSLv3, Cipher is AEAD-CHACHA20-POLY1305-SHA256
Server public key is 2048 bit
Secure Renegotiation IS NOT supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
SSL-Session:
    Protocol  : TLSv1.3
    Cipher    : AEAD-CHACHA20-POLY1305-SHA256
    Session-ID:
    Session-ID-ctx:
    Master-Key:
    Start Time: 1766909362
    Timeout   : 7200 (sec)
    Verify return code: 21 (unable to verify the first certificate)
---
DONE

[mre]

Unfortunately, OpenSSL doesn't provide any additional info; or at least such information is not easy to come by through the Rust sys-crate.

As a test, I tried it on @thomas-zahner's branch, which uses rustls:

cargo install --git https://github.com/thomas-zahner/lychee --branch rustls

❯❯❯ echo 'https://duc.zevv.nl' | lychee -                                                                                                                                                                                                       ✖ ✹
  1/1 ━━━━━━━━━━━━━━━━━━━━ Finished extracting links
🔍 1 Total (in 0s) ✅ 1 OK 🚫 0 Errors

Since this will become the default very soon, I believe we should focus our efforts on that branch. Can you test it on your end?

[AlexeyDemidov]

Have the same issue with lychee <(echo 'https://mariadb.com') on MacOS, while the system curl linked with the system LibreSSL works fine. It seems that the native-tls crate doesn't support TLS 1.3 and mariadb.com is TLS 1.3 only, with no fallback to 1.2.

[mre]

I tried it with Thomas' version:

cargo install --git https://github.com/thomas-zahner/lychee --branch rustls

That worked on my Mac. Can you try?

❯ echo 'https://mariadb.com' | lychee -v -
     [200] https://mariadb.com/

This will be the version we will release soon, which will switch to rustls.