lychee "Timeout" checking links in CI

By Daniel Zoghalchali·Latchkey

lychee gave up on a URL because the server did not respond within the timeout. The link may be fine but slow, or the host is intermittently unreachable from the runner. A timeout counts as an error by default.

What this error means

lychee reports "Timeout" (or "operation timed out") for one or more URLs, and the error count fails the docs job even though the pages load in a browser.

[docs/refs.md]:
  [TIMEOUT] https://slow.example.org/report | Timeout

Errors: 1

Common causes

A slow host exceeds the default timeout

The default per-request timeout is short; a slow or geographically distant host can exceed it while still being reachable.

Transient network flakiness from the runner

Momentary packet loss or DNS delay makes a normally fast link time out on one run.

How to fix it

Raise the timeout and add retries

Give lychee more time per request and retry so a slow-but-valid host passes.

- uses: lycheeverse/lychee-action@v2
  with:
    args: --timeout 30 --max-retries 3 --retry-wait-time 5 './**/*.md'

Exclude hosts that are reliably slow

If a host cannot answer in time, exclude it so its latency does not fail the build.

# lychee.toml
timeout = 30
exclude = ["^https://slow\\.example\\.org"]

How to prevent it

• Set a generous --timeout for docs that link to slow hosts.
• Enable retries so transient timeouts do not fail the job.
• Exclude or allowlist hosts that are known to be slow.

Frequently asked questions

Related guides

References

• GitHub Actions documentation