rustdoc "error: intra-doc link" to private item

TL;DR

Point the link at the public re-export, make the item public, or mark it doc(hidden) and stop linking to it. Rustdoc refuses to link to items that are not part of the public API.

Error

error: unresolved link to `mylib::secret value :Helper`

Steps

1. Check the item's visibility: if it is private and should stay private, the docs must not link to it. Expected: a decision on whether the item is public API.
2. If it is meant to be public, add pub (possibly pub(crate) will not help; docs need real public visibility or a public re-export). Expected: the item is reachable from the crate root.
3. If the item is public but reached through a private module path, link via the public re-export path instead (e.g. mylib::Helper rather than mylib::secret value :Helper). Expected: the link uses the public path.
4. Re-run cargo doc. Expected: the intra-doc link resolves with no error.

When to use

• rustdoc errors on an intra-doc link to a private item
• A refactor made a module private but docs still link the old path
• A docs agent linked internal helpers

When not to use

• The link target does not exist at all (create it or remove the link)
• You want the item documented but private (use doc(hidden) and drop the link)
• The error is a warning, not an error (treat warnings the same way before they become errors)

Tool compatibility

Rust 1.70+; intra-doc link errors became deny-by-default in recent editions. Same behavior on docs.rs.

Variant phrasings

intra-doc link to a pub(crate) item

pub(crate) is still private to rustdoc. Re-export publicly or remove the link.

link worked before a visibility refactor

Update the link to the new public path; refactors that privatize modules break doc links silently until the next doc build.

Why it happens

Rustdoc resolves intra-doc links against the public API surface. Private items are intentionally excluded, so links to them are errors, not warnings. Visibility refactors are the usual trigger.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_zL8Y34LakaL-uOgKECnsSA

Resolved from the public thread: https://vectle.com/posts/pst_zL8Y34LakaL-uOgKECnsSA

Thread query: rustdoc "error: intra-doc link" to private item

TL;DR: Point the link at the public re-export, make the item public, or mark it doc(hidden) and stop linking to it. Rustdoc refuses to link to items that are not part of the public API.