apache/hadoop · error · UnmanglingError

unterminated code point escape: expected semicolon at end.

Error message

unterminated code point escape: expected semicolon at end.

What it means

In the mangled format an escaped code point is a backslash followed by exactly NUM_SLASH_POSITIONS (4) characters and a terminating semicolon (\hhhh;). While scanning, unmangleXmlString counts positions after the backslash; once 4 characters are consumed it demands that the next character be ';'. Anything else throws UnmanglingError("unterminated code point escape: expected semicolon at end.").

Source

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

          } else if (e.equals("'")) {
            bld.append("\'");
          } else if (e.equals("&")) {
            bld.append("&");
          } else if (e.equals("<")) {
            bld.append("<");
          } else if (e.equals("&gt;")) {
            bld.append(">");
          } else {
            throw new UnmanglingError("Unknown entity ref " + e);
          }
          entityRef = null;
        }
      } else  if ((slashPosition >= 0) && (slashPosition < NUM_SLASH_POSITIONS)) {
        escapedCp += ch;
        ++slashPosition;
      } else if (slashPosition == NUM_SLASH_POSITIONS) {
        if (ch != ';') {
          throw new UnmanglingError("unterminated code point escape: " +
              "expected semicolon at end.");
        }
        try {
          bld.appendCodePoint(Integer.parseInt(escapedCp, 16));
        } catch (NumberFormatException e) {
          throw new UnmanglingError("error parsing unmangling escape code", e);
        }
        escapedCp = "";
        slashPosition = -1;
      } else if (ch == '\\') {
        slashPosition = 0;
      } else {
        boolean startingEntityRef = false;
        if (decodeEntityRefs) {
          startingEntityRef = (ch == '&');
        }
        if (startingEntityRef) {
          entityRef = new StringBuilder();

View on GitHub (pinned to 2add963021)

Solutions

1. Restore the semicolon: every backslash escape must be exactly backslash + 4 hex digits + ';'
2. Re-mangle the original string with XMLUtils.mangleXmlString instead of hand-crafting escapes
3. Regenerate the fsimage XML with `hdfs oiv` rather than editing tool output by hand

Example fix

// before
String bad = "a\\0009 b"; // 4 hex digits then space
XMLUtils.unmangleXmlString(bad, false); // throws

// after
String good = "a\\0009; b";
XMLUtils.unmangleXmlString(good, false); // ok

static boolean escapesWellFormed(String s) {
  for (int i = 0; i < s.length(); i++) {
    if (s.charAt(i) == '\\') {
      if (i + 5 >= s.length()) return false;              // truncated
      for (int j = 1; j <= 4; j++) {
        if (Character.digit(s.charAt(i + j), 16) < 0) return false;
      }
      if (s.charAt(i + 5) != ';') return false;            // missing semicolon
      i += 5;
    }
  }
  return true;
}

try {
  XMLUtils.unmangleXmlString(s, false);
} catch (XMLUtils.UnmanglingError e) {
  // malformed escape; quarantine the record and keep processing
}

When it happens

Trigger: unmangleXmlString encounters a backslash + 4 characters followed by a non-semicolon, e.g. "a\0009 b" instead of "a\0009; b". Because mangleXmlString always escapes a literal backslash as \005c;, well-formed mangled strings never hit this — the input was hand-edited, truncated, or never produced by mangleXmlString.

Common situations: Manually repairing fsimage XML values; string truncation at a fixed buffer or column boundary; concatenating mangled fragments incorrectly; retyping escape sequences with typos.

Related errors

• error parsing unmangling escape code
• unterminated code point escape: string broke off in the midd
• 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/91469d49c46a666e. Report an issue: GitHub.