apache/hadoop · error · UnmanglingError

error parsing unmangling escape code

Error message

error parsing unmangling escape code

What it means

After collecting the 4 characters following a backslash, unmangleXmlString parses them as a base-16 code point via Integer.parseInt(escapedCp, 16). A NumberFormatException (non-hex characters present) is wrapped in UnmanglingError("error parsing unmangling escape code") with the original exception chained as the cause.

Source

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

          } else if (e.equals(">")) {
            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();
          entityRef.append("&");
        } else {
          bld.append(ch);
        }
      }
    }

View on GitHub (pinned to 2add963021)

Solutions

1. Escape literal backslashes before unmangling: s.replace("\\", "\\005c;")
2. Only unmangle strings that were produced by XMLUtils.mangleXmlString in the first place
3. Catch UnmanglingError and inspect getCause() instanceof NumberFormatException to pinpoint the bad escape

Example fix

// before
String raw = "C:\\Users\\"; // literal backslashes, not mangled
XMLUtils.unmangleXmlString(raw, false); // can throw

// after
String escaped = raw.replace("\\", "\\005c;");
XMLUtils.unmangleXmlString(escaped, false);

static String escapeRawBackslashes(String s) {
  return s.replace("\\", "\\005c;"); // makes any literal backslash round-trip
}

try {
  XMLUtils.unmangleXmlString(s, false);
} catch (XMLUtils.UnmanglingError e) {
  if (e.getCause() instanceof NumberFormatException) {
    // non-hex digits after a backslash: input contained raw backslashes
  }
}

When it happens

Trigger: The 4 characters after a backslash are not all hex digits — e.g. "\\zzff;", or a literal backslash embedded in the input followed by 4 characters and a semicolon (mangleXmlString escapes real backslashes as \005c;, so this only happens with strings that did not come from that method).

Common situations: Unmangling Windows-style paths or regex text containing raw backslashes; hand-edited escape sequences with typos; encoding mismatches that alter characters inside an escape.

Related errors

• unterminated code point escape: expected semicolon at end.
• 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/f7d72aa03f311a90. Report an issue: GitHub.