Repository navigation
Using a local --base-url breaks fragments in relative links in local files #1896
Description
echo '[a](b.html#a)
[a](/b.html#a)
[a](https://a.com/#asd)' > a.md
cargo run -- a.md --base-url $(pwd) --dump
cargo run -- a.md --dump The first command shows this bug. The hash (which should be a fragment) is treated as part of the file name. This only happens on relative links.
file:///home/x/progs/lychee/b.html%23a
https://a.com/#asd
file:///b.html%23a
For comparison, the second command without --base-url leaves the hashes as hashes so they will get picked up as fragments.
[WARN] Error creating request: InvalidPathToUri("/b.html#a")
https://a.com/#asd
file:///home/x/progs/lychee/b.html#a
I've used --dump for demonstration, but the bug also happens in normal link checking.
$ cargo run -- a.md --base-url $(pwd)
[a.md]:
[ERROR] file:///b.html%23a | Cannot find file: File not found. Check if file exists and path is correct
[ERROR] file:///home/x/progs/lychee/b.html%23a | Cannot find file: File not found. Check if file exists and path is correct
[ERROR] https://a.com/#asd | Network error: Connection failed. Check network connectivity and firewall settings
The bug doesn't happen when we use a file:// base because that gets treated as a remote base for the purposes of parsing.
$ cargo run -- a.md --base-url file://$(pwd) --dump
file:///b.html#a
https://a.com/#asd
file:///home/x/progs/b.html#a
Very fun
Activity
wade-cheng commentedon Nov 30, 2025
I'm a bit confused at what this issue means, but small note: I'm also getting links in local files being broken, ones that seem more simple than yours. This is for the contents of a static site (that is, HTML, not md). I'm running lychee on the file tree obtainable here https://github.com/wade-cheng/wade-cheng.github.io/tree/gh-pages.
That is,
lychee .gives a bajillion warn messages like:It should afaik work, and indeed does if I spin up a local server and point lychee to localhost.
katrinafyi commentedon Dec 3, 2025
@wade-cheng The long and short of it is that you can add
--root-dir $(pwd)to make it work.This is a known pain point. There's merged but unreleased work to improve the error message so it suggests this solution. There's plans to write a documentation page about this. There's discussions to make --root-dir the default behaviour for certain simple cases, including yours.