{"record":{"id":"8a2017f82ae92678","repo":"apache/maven","slug":"entities-are-not-supported-in-strict-mode","errorCode":null,"errorMessage":"Entities are not supported in strict mode","messagePattern":"Entities are not supported in strict mode","errorType":"exception","errorClass":"XMLStreamException","httpStatus":null,"severity":"error","filePath":"src/mdo/reader-stax.vm","lineNumber":686,"sourceCode":"                    return next;\n            }\n        }\n    } //-- int nextTag(XMLStreamReader)\n\n    private String nextText(XMLStreamReader parser, boolean strict) throws XMLStreamException {\n        int eventType = parser.getEventType();\n        if (eventType != XMLStreamReader.START_ELEMENT) {\n            throw new XMLStreamException(\"parser must be on START_ELEMENT to read next text\", parser.getLocation(), null);\n        }\n        eventType = parser.next();\n        StringBuilder result = new StringBuilder();\n        while (true) {\n            if (eventType == XMLStreamReader.CHARACTERS || eventType == XMLStreamReader.CDATA) {\n                result.append(parser.getText());\n            } else if (eventType == XMLStreamReader.ENTITY_REFERENCE) {\n                String val = null;\n                if (strict) {\n                    throw new XMLStreamException(\"Entities are not supported in strict mode\", parser.getLocation(), null);\n                } else if (addDefaultEntities) {\n                    val = DefaultEntitiesHolder.DEFAULT_ENTITIES.get(parser.getLocalName());\n                }\n                if (val != null) {\n                    result.append(val);\n                } else {\n                    result.append(\"&\").append(parser.getLocalName()).append(\";\");\n                }\n            } else if (eventType != XMLStreamReader.COMMENT) {\n                break;\n            }\n            eventType = parser.next();\n        }\n        if (eventType != XMLStreamReader.END_ELEMENT) {\n            throw new XMLStreamException(\n                \"TEXT must be immediately followed by END_ELEMENT and not \" + eventType /*TODO: TYPES[eventType]*/, parser.getLocation(), null);\n        }\n        return result.toString();","sourceCodeStart":668,"sourceCodeEnd":704,"githubUrl":"https://github.com/apache/maven/blob/e4093d4e120eac99d6bdce5ba67cace2f3085c97/src/mdo/reader-stax.vm#L668-L704","documentation":"Inside nextText, an ENTITY_REFERENCE event in element text can only be honored in lenient mode, where DefaultEntitiesHolder substitutes the well-known HTML entities (nbsp, copy, ...). Strict mode refuses any entity substitution and throws, so content is never silently rewritten. Only the five predefined XML entities, resolved by the parser itself, survive a strict read.","triggerScenarios":"Strict read of text containing a named entity beyond &amp; &lt; &gt; &quot; &apos; - e.g. &nbsp; or &copy; in a <description> - or custom entities declared in a DOCTYPE the parser did not resolve.","commonSituations":"HTML pasted into XML text fields; documents authored for lenient consumers then parsed strictly; DTD-reliant content read with DTD processing disabled.","solutions":["Replace named entities with numeric character references (&nbsp; becomes &#160;) or literal UTF-8 characters.","Let a DOCTYPE-loaded DTD resolve the entities before the reader sees them, or restructure to avoid entities.","Parse with strict=false so DefaultEntitiesHolder substitutes the known HTML entities."],"exampleFix":"<!-- before -->\n<description>foo&nbsp;bar</description>\n\n<!-- after -->\n<description>foo&#160;bar</description>","handlingStrategy":"fallback","validationCode":"// crude pre-scan: reject documents with non-predefined named entities before a strict read\nString text = new String(bytes, StandardCharsets.UTF_8);\nMatcher m = Pattern.compile(\"&([a-zA-Z][a-zA-Z0-9]*);\").matcher(text);\nwhile (m.find()) {\n    if (!Set.of(\"amp\", \"lt\", \"gt\", \"quot\", \"apos\").contains(m.group(1))) {\n        throw new IllegalArgumentException(\"unsupported entity: &\" + m.group(1) + \";\");\n    }\n}","typeGuard":null,"tryCatchPattern":"byte[] bytes = in.readAllBytes();\ntry {\n    Model model = reader.read(new ByteArrayInputStream(bytes), true);\n} catch (XMLStreamException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Entities are not supported\")) {\n        // lenient re-parse: DefaultEntitiesHolder substitutes the HTML default entities\n        Model model = reader.read(new ByteArrayInputStream(bytes), false);\n    } else {\n        throw e;\n    }\n}","preventionTips":["Normalize named entities to numeric references at authoring time.","Keep rich text in CDATA or fully escaped form.","Choose strict vs lenient per content source, not per build."],"tags":["xml","stax","entities","strict-mode","encoding"],"backgroundTag":"xml-unsupported-entity","analyzedSha":"e4093d4e120eac99d6bdce5ba67cace2f3085c97","analyzedAt":"2026-08-21T22:58:24.034Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}