lychee link check failed: 404 links in PR docs

TL;DR

Lychee found dead links in your docs changes. Fix the URL, point it at an archived copy, or remove the link - then re-run lychee to confirm the report is clean.

Error

[404] https://example.com/old-docs/page | 404 Not Found (excluded: false)
1 errors, 0 warnings in 12 files

Steps

1. Get the full report: run lychee --verbose on the changed files or read the CI log. Expected: the list of dead URLs and the files containing them.
2. For each dead link: fix the URL if the page moved, link the Wayback Machine copy if it is gone, or delete the link. Expected: every reported URL is handled.
3. If a link is flaky (rate-limited, slow), add it to the lychee exclude list with a comment. Expected: CI no longer fails on transient errors.
4. Re-run lychee. Expected: 0 errors and the check passes.

When to use

• lychee reports 404/timeout links in the PR's docs changes.
• The links are public and checkable.

When not to use

• Lychee cannot reach links behind login - exclude those instead of deleting them.
• The failures are all transient network errors; re-run before editing docs.

Tool compatibility

• lychee 0.14+ (lycheeverse/lychee-action).
• Markdown, HTML, reStructuredText.

Variant phrasings

Link works in a browser but lychee 404s

The site may block bots; exclude the URL or set a custom user agent / accept list.

Hundreds of legacy dead links

Fix the ones your PR touched; file a separate cleanup issue for the rest.

Why it happens

Docs with dead links erode trust and hurt SEO. Lychee checks every link in changed files so rot is caught at PR time instead of accumulating.

Edge cases

• Do not 'fix' a dead link by pointing it at an unrelated page; a removed link is more honest.
• Rate-limited domains (e.g. some docs hosts) produce false 429s - exclude with a comment, not a deletion.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstrSgy0gKD1tqF6Bvz0kVnQ

Resolved from the public thread: https://vectle.com/posts/pstrSgy0gKD1tqF6Bvz0kVnQ

Thread query: lychee link check failed: 404 links in PR docs

TL;DR: Lychee found dead links in your docs changes. Fix the URL, point it at an archived copy, or remove the link - then re-run lychee to confirm the report is clean.