Clarify `Network error` reporting

[ArthurFlag]

Hi and thanks for this tool.

I'm trying to run lychee on https://docs.talon.one with:

lychee --verbose https://docs.talon.one

And I'm getting this output/error:

Error: Network error

Caused by:
    0: error sending request for url (https://docs.talon.one/)
    1: client error (Connect)
    2: bad protocol version

I'm not sure how to diagnose this error, is there a way to get more information about what went wrong?

[mre]

I investigated several related issues:

• reqwest TLS discussion
• Rust users forum thread

First, I tried setting a different user agent:

lychee --user-agent "curl/8.4.0" https://docs.talon.one

This didn't resolve the issue.

Next, I attempted to use different TLS features available in lychee:

• native-tls enables the platform-native TLS crate
• vendored-openssl compiles and statically links a copy of OpenSSL
• rustls-tls enables the alternative rustls TLS crate

All configurations produced the same error.

I tested the SSL certificate using SSL Labs. The certificate appears valid overall, though there are minor chain issues: "Incorrect order, Extra certs." I'm unsure if these issues are related to the lychee failures.

The site runs TLS 1.3, which lychee supports, so there shouldn't be any compatibility problems.

I'm unable to determine why lychee is failing with this particular URL. For additional debugging information, I typically run:

RUST_LOG=trace lychee -vvv https://docs.talon.one

However, this doesn't provide any additional insights in this case.

To help troubleshoot further, could you share your operating system and lychee version?

[ArthurFlag]

Thanks a lot for the quick answer and investigation 🙌 ⭐ !

Here's the info you requested:

• OS: MacOs 15.7
• lychee: 0.21.0

Let me know if you need anything!

[mre]

Thanks.

What's interesting is that this works as expected:

lychee https://talon.one

So it has to have something to do with https://docs.talon.one, which I'm assuming runs on totally different infrastructure.

I can see some differences in the SSL setup: https://www.ssllabs.com/ssltest/analyze.html?d=talon.one&hideResults=on https://www.ssllabs.com/ssltest/analyze.html?d=docs.talon.one&hideResults=on

1. Under Protocols, it shows that talon.one supports TLS 1.2 whereas docs.talon.one does not.
2. Under Additional Certificiats, docs.talon.one says "Chain issues: Incorrect order, Extra certs" whereas talon.one looks fine.

If I had to guess, it's most likely a TLS error. lychee supports TLS 1.2 and 1.3 out of the box, so I'm a little confused by that.

[ArthurFlag]

Does Lychee require individual domain SSL certificates or are there any known issues with wildcard certificates?

[mre]

I am not aware of any wildcard issues. Can you check the reqwest issues? That's what we use under the hood.

[ArthurFlag]

I just checked with muffet as well, and I get this error for every page:

error when reading response headers: small read buffer. Increase ReadBufferSize. 

Which indeed works when I run muffet -b 8192 https://docs.talon.one.

There doesn't seem to be a way to increase buffer size with Lychee, maybe that would be a feature idea?

[mre]

That's strange. I checked the response headers and can only see these?

HTTP/2 200
accept-ranges: bytes
content-disposition: inline; filename="index.html"
content-type: text/html; charset=utf-8
date: Tue, 18 Nov 2025 11:11:46 GMT
last-modified: Mon, 17 Nov 2025 15:26:51 GMT
content-length: 36406

Looks pretty normal to me. (I used curl --dump-header headers.txt https://docs.talon.one for that.)

So I don't quite get why we'd need a larger buffer. Also, if we do, that would be a feature request to reqwest. But if you ask me, that should be an implementation detail and should not fail. I find the muffet error a bit scary.

[ArthurFlag]

I've tried linkchecker and linkinator on the same website and both work fine without any specific options. I'm not so sure how to diagnose the problem further and I also couldn't find a related issue on the reqwest repo so I think we can close this issue.

I appreciate your help in diagnosing things, and overall your project has the best UX among the tools I've tried 👏

[mre]

Hum, well, it could still be a bug in lychee, so let's keep it open for a bit. I would like to investigate more if I get the chance. Apologies for the inconvenience.

[mre]

While I don't think I can fix the immediate issue, I think we can at least provide a slightly better error message. Tried my luck in #1927.

The reason why it works in other tools is likely: - Different TLS implementations (e.g., browser's own TLS, curl with different OpenSSL) - Newer versions of system libraries - Different TLS version negotiation strategies

Here are a few things you could try, but I honestly don't know if anything works: - Update system OpenSSL (most common fix) - Use lychee with rustls-tls feature (pure Rust TLS, doesn't depend on system OpenSSL) - Verify if the server specifically requires TLS 1.3+ (less common)

I did notice that https://docs.talon.one is more aggressive about TLS settings than https://talon.one, which might be a hint. I think it requires TLS 1.3, which we support, but maybe there's a bug somewhere.

[thomas-zahner]

@mre @ArthurFlag I'm unable to reproduce the issue on NixOS. Do you both get the error? I get:

lychee https://docs.talon.one
2/2 ━━━━━━━━━━━━━━━━━━━━ Finished extracting links
🔍 2 Total (in 0s) ✅ 2 OK 🚫 0 Errors

If so I guess that this is related to the macOS specific OpenSSL implementation. Coincidentally, I've started working on switching to rustls. Can you check out the PR, e.g. with:

git fetch origin pull/1928/head:rustls
git switch rustls
cargo run https://docs.talon.one

I get the following, which interestingly enough is quite different than the latest release. But definitely the same result as on master. Not entirely sure which PR caused lychee to find so many more results.

cargo run https://docs.talon.one
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.21s
Running `target/debug/lychee 'https://docs.talon.one'`
59/59 ━━━━━━━━━━━━━━━━━━━━ Finished extracting links
🔍 59 Total (in 0s) ✅ 57 OK 🚫 0 Errors 👻 2 Excluded

Ideally the PR will resolve your issues.

[mre]

Yes, I also got the error, but your branch works indeed!

🔍 59 Total (in 0s) ✅ 57 OK 🚫 0 Errors 👻 2 Excluded

If this also holds for @ArthurFlag, I would suggest to expedite the transition to rustls as per your PR.

[ArthurFlag]

Hi guys, It also worked on my end, thanks a lot for the quick support 👍 🚀 !

[mre]

Good times. Thanks for the feedback and thanks to @thomas-zahner, who did all the work.

[thomas-zahner]

@ArthurFlag Thank you for the feedback and for testing the branch. Really glad to hear it works. I'll try to merge the branch soon then.

PS: keeping this open until #1928 is merged. @mre maybe you confused this with #1935

[mre]

Sorry. 😅