What causes "you must put at the top of the XML file! Got tag {} instead" in apache/hadoop?

Insert ... as the first child of , e.g. -64 for recent layout versions.

apache/hadoop · error · InvalidXmlException

you must put <EDITS_VERSION> at the top of the XML file! Got

Error message

you must put <EDITS_VERSION> at the top of the XML file! Got tag {} instead

What it means

After the root <EDITS> opens, the state machine moves to EXPECT_VERSION and the next start element must be <EDITS_VERSION> (carrying the edits layout version). Any other tag at that position throws InvalidXmlException demanding <EDITS_VERSION> at the top. The version element is mandatory even in hand-built or fixture XML files.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineEditsViewer/OfflineEditsXmlLoader.java:146

      throw new InvalidXmlException("expecting </EDITS>");
    }
  }
  
  @Override
  public void startElement (String uri, String name,
      String qName, Attributes atts) {
    switch (state) {
    case EXPECT_EDITS_TAG:
      if (!name.equals("EDITS")) {
        throw new InvalidXmlException("you must put " +
            "<EDITS> at the top of the XML file! " +
            "Got tag " + name + " instead");
      }
      state = ParseState.EXPECT_VERSION;
      break;
    case EXPECT_VERSION:
      if (!name.equals("EDITS_VERSION")) {
        throw new InvalidXmlException("you must put " +
            "<EDITS_VERSION> at the top of the XML file! " +
            "Got tag " + name + " instead");
      }
      break;
    case EXPECT_RECORD:
      if (!name.equals("RECORD")) {
        throw new InvalidXmlException("expected a <RECORD> tag");
      }
      state = ParseState.EXPECT_OPCODE;
      break;
    case EXPECT_OPCODE:
      if (!name.equals("OPCODE")) {
        throw new InvalidXmlException("expected an <OPCODE> tag");
      }
      break;
    case EXPECT_DATA:
      if (!name.equals("DATA")) {
        throw new InvalidXmlException("expected a <DATA> tag");

View on GitHub (pinned to 2add963021)

Solutions

Insert <EDITS_VERSION>...</EDITS_VERSION> as the first child of <EDITS>, e.g. -64 for recent layout versions.
Prefer generating fixtures with 'hdfs oev -p xml' so the header is always correct.
Copy the version value from an authentic dump of the same Hadoop version rather than guessing.

Example fix

<!-- before -->
<EDITS><RECORD>...</RECORD></EDITS>

<!-- after -->
<EDITS><EDITS_VERSION>-64</EDITS_VERSION><RECORD>...</RECORD></EDITS>

Defensive patterns

Strategy: validation

Validate before calling

try (XMLStreamReader r = XMLInputFactory.newFactory()
        .createXMLStreamReader(new FileInputStream(file))) {
  r.next();                    // <EDITS>
  r.nextTag();                 // first child must be EDITS_VERSION
  if (!"EDITS_VERSION".equals(r.getLocalName())) {
    throw new IOException("First child of <EDITS> must be <EDITS_VERSION>, found <"
        + r.getLocalName() + ">");
  }
}

Try / catch

try {
  loader.loadEdits();
} catch (InvalidXmlException e) {
  if (e.getMessage().contains("<EDITS_VERSION>")) {
    throw new IOException("Missing <EDITS_VERSION> header; regenerate the XML "
        + "with oev or copy the element from a real dump.", e);
  }
  throw e;
}

Prevention

Generate fixtures with oev so the version header is always present and correct.
When templating XML, assert the header element survived the template engine.

When it happens

Trigger: An edits XML where <EDITS_VERSION> is missing (first child is directly a <RECORD>) or was renamed/removed during manual editing or XML generation.

Common situations: Hand-written test fixtures that skip the version element; XSLT/serialization pipelines that drop single-value children; trimming files and accidentally removing the header record.

Related errors

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