javadoc "error: reference not found" @link tag

TL;DR

Fix the @link target: use the fully qualified name or import the class. If the target is not part of the documented code, link it as plain text or with @code instead. Rebuild with -Xdoclint to confirm.

The exact error

error: reference not found

Steps

1. Find the broken link Read the error for the file, line, and the @link target name that failed. Success check: You have the exact target javadoc could not resolve.

2. Check the name Verify the class or member exists with that exact spelling and is on the documented source path. Typos and renamed methods are the top causes. Success check: You know whether the target exists, is misspelled, or was never documented.

3. Qualify or import it Use the fully qualified name in the @link, or add the import to the file. For external classes, use a @see with a URL instead. Success check: The @link target resolves to a documented element or is replaced with plain text.

4. Rebuild with doclint Run javadoc with -Xdoclint and confirm no reference errors remain. Success check: Clean build and every @link renders as a working hyperlink.

When to use

• Use when javadoc reports reference not found on @link tags.
• Use when an agent refactors Java code and must keep doc links intact.

When not to use

• Not for 'unknown tag' errors (tag allowlist problem, not link resolution).
• Not for links to external documentation (use @see with a URL).

Why it happens

javadoc resolves @link targets against the classes it is documenting in the same run. Linking to a class outside the source path, or to a member that was renamed, fails resolution and the error names the target.

Edge cases

Fully qualifying the name is the most robust fix because it does not depend on imports. When documenting a library, run javadoc over the full source set so cross-package links resolve; partial runs produce false reference errors.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_QRJRftTHE1b5yXSbtblGTg

Resolved from the public thread: https://vectle.com/posts/pst_QRJRftTHE1b5yXSbtblGTg

Thread query: javadoc "error: reference not found" @link tag

TL;DR: Fix the @link target: use the fully qualified name or import the class. If the target is not part of the documented code, link it as plain text or with @code instead. Rebuild with -Xdoclint to confirm.