{"record":{"id":"669041feabcc54ab","repo":"apache/hadoop","slug":"unknown-entity-ref","errorCode":null,"errorMessage":"Unknown entity ref {}","messagePattern":"Unknown entity ref (.+?)","errorType":"exception","errorClass":"UnmanglingError","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/util/XMLUtils.java","lineNumber":196,"sourceCode":"    StringBuilder entityRef = null;\n    for (int i = 0; i < str.length(); i++) {\n      char ch = str.charAt(i);\n      if (entityRef != null) {\n        entityRef.append(ch);\n        if (ch == ';') {\n          String e = entityRef.toString();\n          if (e.equals(\"&quot;\")) {\n            bld.append(\"\\\"\");\n          } else if (e.equals(\"&apos;\")) {\n            bld.append(\"\\'\");\n          } else if (e.equals(\"&amp;\")) {\n            bld.append(\"&\");\n          } else if (e.equals(\"&lt;\")) {\n            bld.append(\"<\");\n          } else if (e.equals(\"&gt;\")) {\n            bld.append(\">\");\n          } else {\n            throw new UnmanglingError(\"Unknown entity ref \" + e);\n          }\n          entityRef = null;\n        }\n      } else  if ((slashPosition >= 0) && (slashPosition < NUM_SLASH_POSITIONS)) {\n        escapedCp += ch;\n        ++slashPosition;\n      } else if (slashPosition == NUM_SLASH_POSITIONS) {\n        if (ch != ';') {\n          throw new UnmanglingError(\"unterminated code point escape: \" +\n              \"expected semicolon at end.\");\n        }\n        try {\n          bld.appendCodePoint(Integer.parseInt(escapedCp, 16));\n        } catch (NumberFormatException e) {\n          throw new UnmanglingError(\"error parsing unmangling escape code\", e);\n        }\n        escapedCp = \"\";\n        slashPosition = -1;","sourceCodeStart":178,"sourceCodeEnd":214,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/util/XMLUtils.java#L178-L214","documentation":"XMLUtils.unmangleXmlString(str, true) reverses mangleXmlString: it decodes backslash-hex escapes (\\hhhh;) and, when decodeEntityRefs is true, exactly the five built-in XML entities &quot; &apos; &amp; &lt; &gt;. Any other '&...;' sequence falls into the else branch and throws UnmanglingError(\"Unknown entity ref \" + e), because the decoder has no table for other named or numeric character references.","triggerScenarios":"unmangleXmlString(s, true) on a string containing &nbsp;, &copy;, &#38; or any entity outside the five built-ins — typically a value from an OfflineImageViewer fsimage/XML dump that was post-processed or hand-edited, or a string that never passed through mangleXmlString.","commonSituations":"Running XML tooling (XSLT, HTML sanitizers, pretty-printers) over fsimage XML dumps that injects HTML entities; round-tripping HDFS XML through editors that auto-escape; feeding raw user text containing '&' sequences into the unmangler.","solutions":["Pre-decode or strip non-standard entities before unmangling (e.g. replace \"&nbsp;\" with \"\\u00A0\")","Re-emit the XML using only the five standard entities, or regenerate the fsimage XML with `hdfs oiv -p XML`","If a raw '&' is legitimate text, call unmangleXmlString(s, false) and accept that entity refs stay literal"],"exampleFix":"// before\nString v = XMLUtils.unmangleXmlString(attr, true); // attr = \"a&nbsp;b\" -> UnmanglingError\n\n// after\nString cleaned = attr.replace(\"&nbsp;\", \"\\u00A0\");\nString v = XMLUtils.unmangleXmlString(cleaned, true);","handlingStrategy":"validation","validationCode":"static final java.util.Set<String> OK = java.util.Set.of(\"&quot;\", \"&apos;\", \"&amp;\", \"&lt;\", \"&gt;\");\nstatic final java.util.regex.Pattern ENT = java.util.regex.Pattern.compile(\"&[a-zA-Z#0-9]+;\");\nstatic void checkEntities(String s) {\n  java.util.regex.Matcher m = ENT.matcher(s);\n  while (m.find()) {\n    if (!OK.contains(m.group())) {\n      throw new IllegalArgumentException(\"non-standard entity: \" + m.group());\n    }\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  String v = XMLUtils.unmangleXmlString(s, true);\n} catch (XMLUtils.UnmanglingError e) {\n  // input not produced by mangleXmlString; log and reject the value\n}","preventionTips":["Only unmangle strings produced by XMLUtils.mangleXmlString","Never post-process OIV XML with tools that introduce HTML entities","Pre-validate entity references against the five built-ins before decoding"],"tags":["xml","parsing","entity-references","hdfs","fsimage"],"backgroundTag":"xml-entity-decoding-error","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}