{"record":{"id":"9d2e5b5533c27873","repo":"quarkusio/quarkus","slug":"could-not-parse-html-entity-abbrev-in-text","errorCode":null,"errorMessage":"Could not parse HTML entity &${abbrev}; in\n\n${text}\n\n","messagePattern":"Could not parse HTML entity &(.+?); in\n\n(.+?)\n\n","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/formatter/JavadocToAsciidocTransformer.java","lineNumber":493,"sourceCode":"                        switch (abbrev) {\n                            case \"lt\":\n                                sb.append('<');\n                                break;\n                            case \"gt\":\n                                sb.append('>');\n                                break;\n                            case \"nbsp\":\n                                sb.append(\"{nbsp}\");\n                                break;\n                            case \"amp\":\n                                sb.append('&');\n                                break;\n                            default:\n                                try {\n                                    int code = Integer.parseInt(abbrev);\n                                    sb.append((char) code);\n                                } catch (NumberFormatException e) {\n                                    throw new RuntimeException(\n                                            \"Could not parse HTML entity &\" + abbrev + \"; in\\n\\n\" + text + \"\\n\\n\");\n                                }\n                                break;\n                        }\n                    }\n                    break;\n                case '\\r':\n                    if (i + 1 < text.length() && text.charAt(i + 1) == '\\n') {\n                        /* Ignore \\r followed by \\n */\n                    } else {\n                        /* A Mac single \\r: replace by \\n */\n                        sb.append('\\n');\n                    }\n                    break;\n                default:\n                    sb.append(ch);\n\n            }","sourceCodeStart":475,"sourceCodeEnd":511,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/formatter/JavadocToAsciidocTransformer.java#L475-L511","documentation":"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.","triggerScenarios":"Config Javadoc contains an HTML entity like &nbsp; or &foo; that is not in the transformer's entity switch and is not a decimal number, e.g. &nbsp; or a hex entity &x27;.","commonSituations":"Extension authors pasting HTML-encoded text (from web editors) into Javadoc; using &nbsp; or symbolic entities like &mdash; not covered by the mapping; typos like &#x27; written without the '#'.","solutions":["Replace the unknown entity with the literal character or its decimal form (&#160; instead of &nbsp;)","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"],"exampleFix":"// before\n/** Speed &nbsp; in ms */\n// after\n/** Speed in ms */","handlingStrategy":"validation","validationCode":"java.util.regex.Matcher m = java.util.regex.Pattern.compile(\"&([a-zA-Z0-9#]+);\").matcher(text);\nwhile (m.find()) {\n    String abbrev = m.group(1);\n    if (!knownNamedEntities.contains(abbrev)) {\n        try { Integer.parseInt(abbrev); } catch (NumberFormatException e) {\n            throw new IllegalArgumentException(\"Unknown HTML entity &\" + abbrev + \"; in Javadoc\");\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    return htmlToAsciidoc(text);\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Could not parse HTML entity\")) {\n        log.warn(e.getMessage());\n        return null; // skip malformed doc\n    }\n    throw e;\n}","preventionTips":["Use literal characters or &#NNN; decimal entities in Javadoc","Never use &nbsp; or named entities not in the transformer mapping","Prefer Asciidoc escapes over HTML entities","Lint Javadoc for HTML entities in CI"],"tags":["annotation-processor","javadoc","html","parsing"],"backgroundTag":"unrecognized-html-entity","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}