HMCL-dev/HMCL · error · java.io.IOException

Version tag not found

Error message

Version tag not found

What it means

Thrown when loading a Litematica schematic (.litematic) file if the root NBT compound contains no 'Version' tag. HMCL reads this integer tag to determine the schematic format version before parsing the rest of the file, so a file without it is not a valid litematic.

Solutions

1. Verify the file is a genuine .litematic created by the Litematica mod; re-export it from the game.
2. Re-download the schematic file — it may be truncated or corrupted.
3. Convert other schematic formats (e.g. .schem) to .litematic with a converter tool before loading.

Example fix

// before: NBT root lacks Version
{"Metadata": {...}, "Regions": {...}}
// after (valid litematic root)
{"Version": 5, "MinecraftDataVersion": 3465, "Metadata": {...}, "Regions": {...}}

NBT root = readRoot(file);
if (root == null || !root.containsKey("Version"))
    throw new IOException("not a valid litematic: missing Version tag");

try {
    LitematicFile.load(file);
} catch (IOException e) {
    if (e.getMessage().equals("Version tag not found")) {
        // file is not a valid litematic; convert or re-export it
    }
}

When it happens

Trigger: LitematicFile.load() reads the GZIP-compressed NBT compound and root.get("Version") returns null — the file exists but its NBT structure lacks the Version entry.

Common situations: Renaming a non-litematic NBT file (e.g. a schematic from WorldEdit or a structure block file) to .litematic; a corrupted/truncated download; a litematic saved by a tool writing a different schema.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Version tag is not an integer
• Metadata tag is not a compound tag
• Metadata tag not found
• is missing
• level.dat missing Data

AI-assisted analysis of HMCL-dev/HMCL@24702dc5a0 (2026-09-10). Data as JSON: /api/errors/437b8d5ed2a167c5. Report an issue: GitHub.

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/schematic/LitematicFile.java:50

/// @author Glavo
/// @see <a href="https://litemapy.readthedocs.io/en/v0.9.0b0/litematics.html">The Litematic file format</a>
public final class LitematicFile {

    private static @Nullable String tryGetString(Tag tag) {
        return tag instanceof StringTag stringTag ? stringTag.get() : null;
    }

    public static LitematicFile load(Path file) throws IOException {

        CompoundTag root;
        try (InputStream in = new GZIPInputStream(Files.newInputStream(file))) {
            root = NBTCodec.of().readTag(in, TagType.COMPOUND);
        }

        Tag versionTag = root.get("Version");
        if (versionTag == null)
            throw new IOException("Version tag not found");
        else if (!(versionTag instanceof IntTag))
            throw new IOException("Version tag is not an integer");

        Tag metadataTag = root.get("Metadata");
        if (metadataTag == null)
            throw new IOException("Metadata tag not found");
        else if (!(metadataTag instanceof CompoundTag))
            throw new IOException("Metadata tag is not a compound tag");

        int regions = 0;
        if (root.get("Regions") instanceof CompoundTag regionsTag)
            regions = regionsTag.size();

        return new LitematicFile(file, (CompoundTag) metadataTag,
                ((IntTag) versionTag).getValue(),
                root.getIntOrZero("SubVersion"),
                root.getIntOrZero("MinecraftDataVersion"),
                regions

View on GitHub (pinned to 24702dc5a0)