javadoc error: reference not found @link tag

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

Allow the tag with -Xdoclint, add it via -tag apiNote:a, or disable the missing-tag check. The cleanest long-term fix is upgrading the JDK, since apiNote is standard in newer releases. Verify the build passes with -Werror.

The exact error

error: unknown tag: apiNote

Steps

1. Confirm the JDK version Run javac -version and javadoc -version. JDK 8 doclint rejects tags it does not know, including apiNote. Success check: You know the exact JDK running the build.

2. Declare the custom tag Pass -tag 'apiNote:a:API Note:' to javadoc so doclint accepts the tag as valid. Success check: The tag is declared and the error moves or disappears.

3. Or relax doclint Use -Xdoclint:none to disable doclint, or -Xdoclint:-missing to keep checks but allow unknown tags. Prefer the narrowest relaxation. Success check: The build passes with the minimal doclint change.

4. Verify with -Werror Run the full javadoc build with -Werror and confirm zero errors. Success check: Clean javadoc build with errors promoted and none remaining.

When to use

• Use when JDK 8 javadoc rejects apiNote, implSpec, or implNote tags.
• Use when a project must stay on JDK 8 but uses newer documentation tags.

When not to use

• Not for 'reference not found' errors (link resolution, not tag allowlisting).
• Not for HTML errors in comments (different doclint check).

Why it happens

JDK 8 enabled doclint by default with -Werror in many builds, and its tag list predates apiNote. Code written against newer JDK conventions fails on the older toolchain even though the tags are legitimate.

Edge cases

Upgrading the JDK is the durable fix; doclint relaxations are stopgaps that hide other documentation problems. If the project documents against multiple JDKs, gate the -tag flags on the JDK version in the build script.

Provenance

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

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

Thread query: javadoc "error: unknown tag: apiNote" JDK 8 doclint

TL;DR: Allow the tag with -Xdoclint, add it via -tag apiNote:a, or disable the missing-tag check. The cleanest long-term fix is upgrading the JDK, since apiNote is standard in newer releases. Verify the build passes with -Werror.

Not specified by the original author.

TL;DR: Point the ref command at the exact documented name. "unable to resolve reference to" means the ref names something doxygen never documented - a typo, a missing namespace qualifier, or a target excluded from the build. Use the fully qualified name, confirm the target page exists in the output, and fall back to plain text when the target is intentionally undocumented.

warning: unable to resolve reference to 'ConfigParser' for ref command

1. Find every broken reference:

   doxygen Doxyfile 2>&1 | grep "unable to resolve reference"

   Expected: one line per broken ref, naming the target doxygen could not find.

2. Check whether the target is documented at all: search the generated HTML output for the symbol name. If nothing matches, the target was never documented.
3. Fix the ref to the fully qualified name, for example docs::ConfigParser instead of the bare ConfigParser.

4. Re-run:

   doxygen Doxyfile

   Expected: the warnings are gone, and the link in the HTML output points at the target's page.

5. If the target lives in excluded code (an EXCLUDE pattern or an undocumented file), replace the ref with plain text - linking at an undocumented target will never resolve.

Use this when

• doxygen warns "unable to resolve reference to" for a ref command
• A cross-reference in the docs renders as dead text
• You renamed or moved a class and the old references broke

Not for this skill when

• The warning is "documented symbol was not declared or defined" - that is a stale comment block, a different fix
• The target should be documented but is not - fix the target's own documentation first
• Automatic linking already handles the name - plain words that match documented symbols link without an explicit ref

Variant phrasings

• "doxygen unable to resolve reference"
• "doxygen ref command unresolved"
• "warning: unable to resolve reference to"

Why it happens

A ref is an explicit link: doxygen looks up the exact name you give it in the documented symbol table. A typo, a missing namespace qualifier, or a target that was never documented (or was excluded) leaves the lookup with nothing to point at.

Edge cases

• Overloaded names can resolve to the wrong overload; qualify with the class or namespace to disambiguate.
• Members of undocumented classes cannot be reference targets even if the member itself has a comment.
• Case matters: ConfigParser and configParser are different targets.

Provenance

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

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

Thread query: doxygen "unable to resolve reference to" class error

TL;DR: