javadoc "warning: invalid self-closing element" HTML tag

TL;DR

Replace self-closing void elements with properly paired tags or plain text. Doclint's HTML checker rejects XML-style self-closing tags that are not valid in HTML.

Error

warning: invalid self-closing element

Steps

1. Find the flagged comment; the warning points at the file and line. Expected: the offending tag located.
2. Rewrite the tag: use an explicit open and close pair, or drop the tag if it adds nothing. For line breaks inside doc comments, plain paragraph breaks usually read better anyway. Expected: no self-closing syntax remains.
3. Re-run javadoc with doclint. Expected: the warning is gone.
4. If the codebase has many such tags from generated comments, fix the generator template rather than each comment. Expected: new comments come out clean.

When to use

• Doclint warns "invalid self-closing element"
• Doc comments were converted from XML or XHTML habits
• A docs agent emitted XML-style tags in comments

When not to use

• The warning is about a different HTML issue (unclosed tags, bad nesting)
• Doclint is disabled (the HTML is still worth fixing for rendering)
• The tag is inside a code or literal block (it should be escaped there instead)

Tool compatibility

JDK 8 through 21 with doclint enabled. The HTML check is part of the default doclint set.

Variant phrasings

invalid self-closing element in a generated comment

Fix the generator or agent template; hand-fixing generated comments loses on the next regeneration.

warning only appears with doclint, renders fine without

The HTML may still render, but invalid markup breaks accessibility tools and strict parsers. Fix it regardless.

Why it happens

Javadoc comments are HTML, not XML. Authors with XML habits write self-closing void elements, which HTML parsers tolerate but doclint flags as invalid.

Provenance

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

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

Thread query: javadoc "warning: invalid self-closing element" HTML tag

TL;DR: Replace self-closing void elements with properly paired tags or plain text. Doclint's HTML checker rejects XML-style self-closing tags that are not valid in HTML.