apache/hadoop · error · UnmanglingError

unterminated entity ref starting with {}

Error message

unterminated entity ref starting with {}

What it means

With decodeEntityRefs=true, a '&' starts an entity reference that must be closed by ';' before the string ends. If the scan loop finishes while entityRef is still open, unmangleXmlString throws UnmanglingError("unterminated entity ref starting with " + the partial text accumulated so far).

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/util/XMLUtils.java:231

        escapedCp = "";
        slashPosition = -1;
      } else if (ch == '\\') {
        slashPosition = 0;
      } else {
        boolean startingEntityRef = false;
        if (decodeEntityRefs) {
          startingEntityRef = (ch == '&');
        }
        if (startingEntityRef) {
          entityRef = new StringBuilder();
          entityRef.append("&");
        } else {
          bld.append(ch);
        }
      }
    }
    if (entityRef != null) {
      throw new UnmanglingError("unterminated entity ref starting with " +
          entityRef.toString());
    } else if (slashPosition != -1) {
      throw new UnmanglingError("unterminated code point escape: string " +
          "broke off in the middle");
    }
    return bld.toString();
  }
  
  /**
   * Add a SAX tag with a string inside.
   *
   * @param contentHandler     the SAX content handler
   * @param tag                the element tag to use  
   * @param val                the string to put inside the tag
   */
  public static void addSaxString(ContentHandler contentHandler,
      String tag, String val) throws SAXException {
    contentHandler.startElement("", "", tag, new AttributesImpl());

View on GitHub (pinned to 2add963021)

Solutions

1. Terminate the entity: append the missing ';' ("&amp" -> "&")
2. If the '&' is literal text rather than an entity, escape it as & first or call with decodeEntityRefs=false
3. Validate string completeness (balanced quotes, matching tags, expected length) before unmangling

Example fix

// before
XMLUtils.unmangleXmlString("A &amp B", true); // '&' never closed by ';' -> throws

// after
XMLUtils.unmangleXmlString("A & B", true); // ok

static boolean entityClosed(String s) {
  return s.lastIndexOf('&') <= s.lastIndexOf(';');
}

try {
  XMLUtils.unmangleXmlString(s, true);
} catch (XMLUtils.UnmanglingError e) {
  // string ended mid-entity; fix truncation at the source and retry
}

When it happens

Trigger: The input ends inside an entity — e.g. "AT&amp" (missing ';') or a bare trailing '&' — while decodeEntityRefs is true. Every character after the '&' is appended to the pending ref, so the message can include trailing junk such as "&amp B".

Common situations: Truncated values read from fsimage XML; column-limited or tail-cut copies of XML content; user input containing a bare ampersand passed to the decoder.

Related errors

• Unknown entity ref {}
• unterminated code point escape: expected semicolon at end.
• error parsing unmangling escape code
• unterminated code point escape: string broke off in the midd
• no entry found for {}

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/95705c10b98d3c3b. Report an issue: GitHub.