What causes "Could not parse HTML entity &${abbrev}; in ${text} " in quarkusio/quarkus?

Replace the unknown entity with the literal character or its decimal form ( instead of )

Could not parse HTML entity &${abbrev}; in ${text}

Error message

Could not parse HTML entity &${abbrev}; in

${text}

What it means

unescapeHtmlEntities converts HTML entities found in Javadoc text. Named entities have a fixed mapping; for unrecognized ones it attempts to parse the abbreviation as a numeric character code. If the entity is neither mapped nor numeric (Integer.parseInt fails), it throws a RuntimeException naming the entity and surrounding text.

Source

Thrown at core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/formatter/JavadocToAsciidocTransformer.java:493

                        switch (abbrev) {
                            case "lt":
                                sb.append('<');
                                break;
                            case "gt":
                                sb.append('>');
                                break;
                            case "nbsp":
                                sb.append("{nbsp}");
                                break;
                            case "amp":
                                sb.append('&');
                                break;
                            default:
                                try {
                                    int code = Integer.parseInt(abbrev);
                                    sb.append((char) code);
                                } catch (NumberFormatException e) {
                                    throw new RuntimeException(
                                            "Could not parse HTML entity &" + abbrev + "; in\n\n" + text + "\n\n");
                                }
                                break;
                        }
                    }
                    break;
                case '\r':
                    if (i + 1 < text.length() && text.charAt(i + 1) == '\n') {
                        /* Ignore \r followed by \n */
                    } else {
                        /* A Mac single \r: replace by \n */
                        sb.append('\n');
                    }
                    break;
                default:
                    sb.append(ch);

            }

View on GitHub (pinned to e1c734241f)

Solutions

Replace the unknown entity with the literal character or its decimal form (  instead of  )
Use Asciidoc syntax instead of HTML entities in the Javadoc
Extend/patch the entity mapping switch if you maintain the processor
Find the offending comment via the text snippet in the message and clean it up

Example fix

// before
/** Speed &nbsp; in ms */
// after
/** Speed in ms */

Defensive patterns

Strategy: validation

Validate before calling

java.util.regex.Matcher m = java.util.regex.Pattern.compile("&([a-zA-Z0-9#]+);").matcher(text);
while (m.find()) {
    String abbrev = m.group(1);
    if (!knownNamedEntities.contains(abbrev)) {
        try { Integer.parseInt(abbrev); } catch (NumberFormatException e) {
            throw new IllegalArgumentException("Unknown HTML entity &" + abbrev + "; in Javadoc");
        }
    }
}

Try / catch

try {
    return htmlToAsciidoc(text);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Could not parse HTML entity")) {
        log.warn(e.getMessage());
        return null; // skip malformed doc
    }
    throw e;
}

Prevention

Use literal characters or &#NNN; decimal entities in Javadoc
Never use   or named entities not in the transformer mapping
Prefer Asciidoc escapes over HTML entities
Lint Javadoc for HTML entities in CI

When it happens

Trigger: Config Javadoc contains an HTML entity like   or &foo; that is not in the transformer's entity switch and is not a decimal number, e.g.   or a hex entity &x27;.

Common situations: Extension authors pasting HTML-encoded text (from web editors) into Javadoc; using   or symbolic entities like — not covered by the mapping; typos like ' written without the '#'.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/9d2e5b5533c27873. Report an issue: GitHub.