apache/hadoop · error · IOException

Got unxpected characters while looking for {expected}: {ev.a

Error message

Got unxpected characters while looking for {expected}: {ev.asCharacters().getData()}

What it means

expectTag tolerates whitespace-only CHARACTERS events between tags but throws when it finds non-whitespace character data where a tag was expected. In oiv XML, text only ever appears inside leaf value elements, so stray character data means a value lost its wrapping tag or text was pasted at the wrong nesting level - typically the residue of hand edits or a broken transform.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/OfflineImageReconstructor.java:202

   *
   * @return             The next tag start or end event.
   */
  private XMLEvent expectTag(String expected, boolean allowEnd)
      throws IOException {
    XMLEvent ev = null;
    while (true) {
      try {
        ev = events.nextEvent();
      } catch (XMLStreamException e) {
        throw new IOException("Expecting " + expected +
            ", but got XMLStreamException", e);
      }
      switch (ev.getEventType()) {
      case XMLEvent.ATTRIBUTE:
        throw new IOException("Got unexpected attribute: " + ev);
      case XMLEvent.CHARACTERS:
        if (!ev.asCharacters().isWhiteSpace()) {
          throw new IOException("Got unxpected characters while " +
              "looking for " + expected + ": " +
              ev.asCharacters().getData());
        }
        break;
      case XMLEvent.END_ELEMENT:
        if (!allowEnd) {
          throw new IOException("Got unexpected end event " +
              "while looking for " + expected);
        }
        return ev;
      case XMLEvent.START_ELEMENT:
        if (!expected.startsWith("[")) {
          if (!ev.asStartElement().getName().getLocalPart().
                equals(expected)) {
            throw new IOException("Failed to find <" + expected + ">; " +
                "got " + ev.asStartElement().getName().getLocalPart() +
                " instead.");
          }

View on GitHub (pinned to 2add963021)

Solutions

Use the offending data named in the message (or xmllint) to locate the text, then re-wrap it in the correct leaf element or delete it
Regenerate the XML from the original fsimage and redo the edit with a DOM/XPath tool
Never edit oiv XML with sed/awk - use a library that preserves structure

Example fix

<!-- before: stray value inside a container -->
<INodeSection><numInodes>1</numInodes>16400<inode>...</inode></INodeSection>

<!-- after -->
<INodeSection><numInodes>1</numInodes><inode><id>16400</id>...</inode></INodeSection>

Defensive patterns

Strategy: validation

Validate before calling

# Container sections must not carry non-whitespace text directly
xmllint --xpath 'string(//INodeSection/text()[normalize-space()])' fsimage.xml 2>/dev/null |
  grep -q '^$' || { echo 'stray text inside a section - re-wrap or remove it'; exit 1; }

Prevention

Edit with DOM/XPath libraries that keep values inside their leaf tags
After bulk edits, diff text nodes of containers against a clean dump
Prefer regenerating the XML over patching misplaced values

When it happens

Trigger: ReverseXML where non-whitespace text sits directly inside a container element (e.g. loose text inside <INodeSection> next to <inode> children), a value moved outside its leaf tag, or an append/merge that left a fragment between elements. The message includes the offending character data, which pinpoints the break.

Common situations: Manual edits to rename paths or adjust quotas that paste values at the wrong level; diff/patch applications that drop a tag but keep its text; scripted text substitutions that eat a delimiter tag.

Related errors

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