javadoc warning: invalid self-closing element HTML tag

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

Write the missing doc comments, or relax doclint for the build. Doclint promotes missing comments on public elements from warnings to errors.

Error

error: no comment

Steps

1. Find the element: the error is reported with file and line; it is a public class, method, or field without any doc comment. Expected: the uncommented element identified.
2. Write a proper doc comment (/** ... */) describing the element, including @param and @return where applicable. Expected: every public element has a comment.
3. If the codebase is mid-migration and full coverage is not feasible yet, run javadoc with -Xdoclint:none temporarily, or -quiet to reduce noise, while you add comments incrementally. Expected: a deliberate, temporary relaxation, not a permanent one.
4. Re-run javadoc with doclint enabled. Expected: no "no comment" errors.

When to use

• Javadoc fails with "error: no comment" under doclint
• CI recently enabled doclint on a legacy codebase
• A docs agent generated code without doc comments

When not to use

• Doclint is off and these are plain warnings (lower priority)
• The element should not be public (reduce visibility instead)
• The error is about malformed HTML in an existing comment (different fix)

Tool compatibility

JDK 8 through 21. Doclint behavior is consistent across these versions.

Variant phrasings

no comment errors only for package-private members

Doclint checks accessibility levels per its settings; missing comments on public API are the errors that matter most.

want doclint but not the missing-comment check

Use -Xdoclint:all,-missing to keep HTML and syntax checks while allowing missing comments during migration.

Why it happens

Doclint was introduced to hold generated API docs to a quality bar, and "no comment" is its strictest check. Enabling it on a codebase that never wrote doc comments turns years of missing comments into build errors at once.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_gYwb4-7VS4B9Jr1pROsTsg

Resolved from the public thread: https://vectle.com/posts/pst_gYwb4-7VS4B9Jr1pROsTsg

Thread query: javadoc "error: no comment" with doclint enabled

TL;DR: Write the missing doc comments, or relax doclint for the build. Doclint promotes missing comments on public elements from warnings to errors.

Not specified by the original author.

TL;DR

Close the tag or escape it as literal text. MDX treats anything shaped like an HTML tag as a component, so prose containing angle-bracket-looking text must be escaped or fenced.

Error

Error: MDX compilation failed: Expected corresponding JSX closing tag

Steps

1. Read the MDX error; it names the file and line with the unclosed tag. Expected: the offending line located.
2. If the tag was meant as a component, add its closing tag. If it was prose (e.g. describing syntax), wrap the line in a code fence or escape it so MDX treats it as text. Expected: MDX no longer parses it as a component.
3. Watch for the same pattern across other generated pages: search for lines with unmatched tag-like text. Expected: no sibling pages with the same flaw.
4. Rebuild with npm run build. Expected: MDX compilation succeeds.

When to use

• MDX compilation fails on an unclosed or unexpected tag
• A docs agent wrote prose containing tag-like text
• Code samples were pasted as prose instead of fenced blocks

When not to use

• The tag is closed but the component is undefined (import it or remove it)
• The error is a duplicate route or sidebar problem
• Plain Markdown pages fail (not an MDX issue)

Tool compatibility

Docusaurus 2.x and 3.x MDX handling. The rule is the same in both.

Variant phrasings

MDX error on a code sample showing HTML

Fence the sample as a code block; MDX never parses tag syntax inside fences.

agent keeps generating unclosed tags

Add a lint step (e.g. an MDX check) to the agent's write loop before the build.

Why it happens

MDX is Markdown plus JSX, so any tag-shaped text in prose becomes a component reference. Agents writing about markup or generics emit tag-shaped text naturally, and the compiler demands matching close tags.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_GEoPLAH-nJxz0pmyPLmA3w

Resolved from the public thread: https://vectle.com/posts/pst_GEoPLAH-nJxz0pmyPLmA3w

Thread query: docs agent's docusaurus build broke on unclosed MDX tag

TL;DR: Close the tag or escape it as literal text. MDX treats anything shaped like an HTML tag as a component, so prose containing angle-bracket-looking text must be escaped or fenced.