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

Version tag is not an integer

Error message

Version tag is not an integer

What it means

Thrown when loading a Litematica schematic (.litematic) file if the 'Version' NBT tag exists but is not an IntTag. HMCL expects the schematic format version to be a plain NBT integer; any other tag type means the file does not conform to the litematic format.

Solutions

1. Re-export the litematic with the Litematica mod so Version is written as an NBT int.
2. Fix the generating script/tool to write Version as an NBT IntTag.
3. Re-download the file if it may be corrupted; verify it loads in Litematica in-game.

Example fix

// before
Version: "5" (StringTag)
// after
Version: 5 (IntTag)

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

if (versionTag instanceof IntTag intTag) {
    int version = intTag.getValue(); // safe to use
}

try {
    LitematicFile.load(file);
} catch (IOException e) {
    if (e.getMessage().equals("Version tag is not an integer")) {
        // re-export the schematic or fix the writer tool
    }
}

When it happens

Trigger: LitematicFile.load() finds a 'Version' tag in the root compound, but its concrete type is not IntTag (e.g. StringTag "5", LongTag, or CompoundTag) — typically from a hand-crafted or tool-written NBT file.

Common situations: Files produced by custom scripts writing Version as a string or long; corrupted or hand-edited NBT data; a file renamed to .litematic that is actually another NBT-based format.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Metadata tag is not a compound tag
• Version tag not found
• Metadata tag not found
• Config is not an object:
• Expected JsonObject but got

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

Appendix: source

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

/// @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)