apache/hadoop · error · UnmanglingError

unterminated code point escape: string broke off in the midd

Error message

unterminated code point escape: string broke off in the middle

What it means

If the string ends while a backslash escape is still in progress (slashPosition != -1 — fewer than 4 hex digits were consumed after the '\', or the 4 digits were consumed but end-of-string arrived before the ';'), unmangleXmlString throws UnmanglingError("unterminated code point escape: string broke off in the middle"). This is the truncation twin of the 'expected semicolon' error, detected after the loop.

Source

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

        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());
    char c[] = mangleXmlString(val, false).toCharArray();
    contentHandler.characters(c, 0, c.length);
    contentHandler.endElement("", "", tag);

View on GitHub (pinned to 2add963021)

Solutions

1. Restore the full \\hhhh; sequence including the semicolon
2. Re-copy the original mangled value from its source instead of repairing by hand
3. Guard with a completeness check before unmangling: every '\' must be followed by 4 hex digits and a ';'

Example fix

// before
XMLUtils.unmangleXmlString("tab\\000", false); // escape cut off -> throws

// after
XMLUtils.unmangleXmlString("tab\\0009;", false); // ok

static boolean escapesWellFormed(String s) {
  for (int i = 0; i < s.length(); i++) {
    if (s.charAt(i) == '\\') {
      if (i + 5 >= s.length() || s.charAt(i + 5) != ';') return false;
      i += 5;
    }
  }
  return true;
}

try {
  XMLUtils.unmangleXmlString(s, false);
} catch (XMLUtils.UnmanglingError e) {
  // escape cut off mid-sequence; re-read the full source value
}

When it happens

Trigger: Input ending in an incomplete escape: "abc\\00" or "abc\\0041" with no trailing semicolon — the character cut lands anywhere between the backslash and the required ';'.

Common situations: Value truncated mid-escape by a fixed-width cut or partial stream read; manual deletion of characters in fsimage XML; splitting a mangled string on a boundary that lands inside an escape.

Related errors

• unterminated code point escape: expected semicolon at end.
• error parsing unmangling escape code
• Unknown entity ref {}
• unterminated entity ref starting with {}
• no entry found for {}

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