markdown-link-check "dead link found" in CI

By Kaveh Alemi·Latchkey

markdown-link-check parsed each Markdown file and probed every link. It marks unreachable ones as dead and exits non-zero when any file has a dead link. A JSON config controls ignores, retries, and per-host headers.

What this error means

markdown-link-check prints "[x] https://example.com/gone -> Status: 404" and ends with "ERROR: 1 dead links found", failing the job.

FILE: docs/guide.md
  [x] https://example.com/gone -> Status: 404
  [/] 24 links checked.

ERROR: 1 dead links found!

Common causes

A genuinely broken or moved link

The URL returns 404 or does not resolve, so the tool marks it dead.

A reachable link the tool cannot verify

Auth-gated or bot-blocked hosts return non-2xx to the checker, or rate-limit it with 429.

How to fix it

Configure ignores and 429 retries

1. Create a config file with ignorePatterns for unverifiable hosts.
2. Enable retryOn429 so throttled links are retried.
3. Pass the config with --config.

{
  "ignorePatterns": [{ "pattern": "^https://linkedin.com" }],
  "retryOn429": true,
  "aliveStatusCodes": [200, 206]
}

Run the maintained action with the config

The gaurav-nelson action wraps the CLI and reads your config file.

- uses: gaurav-nelson/github-action-markdown-link-check@v1
  with:
    config-file: 'mlc-config.json'

How to prevent it

• Keep an ignorePatterns list for hosts that block checkers.
• Enable retryOn429 so throttled links do not fail the build.
• Check links on a schedule to catch external link rot.

Frequently asked questions

Related guides

References

• GitHub Actions documentation