lychee "N errors" broken links (404) in CI

lychee crawled the links in your Markdown and HTML and reported some as errors, most often HTTP 404. When any link fails and no allowlist covers it, lychee exits non-zero and fails the job.

What this error means

lychee prints a summary like "Errors: 3" with lines showing the failing URL and status, such as "[404] https://example.com/old-page | Not Found".

lychee

Issues found in 2 inputs. Find details below.

[docs/guide.md]:
  [404] https://example.com/old-page | Not Found

Errors: 1

Common causes

A link target moved or was removed

The page returns 404 because the URL changed or the resource was deleted, so the link is genuinely dead.

A valid link that lychee cannot reach

Some hosts block bots or require auth, returning 403/404 to the checker even though the page exists in a browser.

How to fix it

Fix dead links, allowlist unreachable hosts

Update or remove links that truly 404.
For hosts that block checkers, add an exclude pattern.
Re-run lychee to confirm zero errors.

lychee.toml

# lychee.toml
exclude = [
  "^https://linkedin\\.com",
  "^https://example\\.com/known-flaky"
]

Run lychee via the action with a cache

The official action checks links and can cache results so unchanged links are not re-hit every run.

.github/workflows/links.yml

- uses: lycheeverse/lychee-action@v2
  with:
    args: --cache --max-cache-age 1d './**/*.md'

How to prevent it

Keep an exclude list for hosts that block automated checkers.
Cache lychee results so only changed links are re-checked.
Run the link check on a schedule so external rot is caught early.