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.

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.