{"record":{"id":"22579e23fc045d98","repo":"HMCL-dev/HMCL","slug":"version-tag-is-not-an-integer","errorCode":null,"errorMessage":"Version tag is not an integer","messagePattern":"Version tag is not an integer","errorType":"exception","errorClass":"java.io.IOException","httpStatus":null,"severity":"error","filePath":"HMCLCore/src/main/java/org/jackhuang/hmcl/schematic/LitematicFile.java","lineNumber":52,"sourceCode":"/// @see <a href=\"https://litemapy.readthedocs.io/en/v0.9.0b0/litematics.html\">The Litematic file format</a>\npublic final class LitematicFile {\n\n    private static @Nullable String tryGetString(Tag tag) {\n        return tag instanceof StringTag stringTag ? stringTag.get() : null;\n    }\n\n    public static LitematicFile load(Path file) throws IOException {\n\n        CompoundTag root;\n        try (InputStream in = new GZIPInputStream(Files.newInputStream(file))) {\n            root = NBTCodec.of().readTag(in, TagType.COMPOUND);\n        }\n\n        Tag versionTag = root.get(\"Version\");\n        if (versionTag == null)\n            throw new IOException(\"Version tag not found\");\n        else if (!(versionTag instanceof IntTag))\n            throw new IOException(\"Version tag is not an integer\");\n\n        Tag metadataTag = root.get(\"Metadata\");\n        if (metadataTag == null)\n            throw new IOException(\"Metadata tag not found\");\n        else if (!(metadataTag instanceof CompoundTag))\n            throw new IOException(\"Metadata tag is not a compound tag\");\n\n        int regions = 0;\n        if (root.get(\"Regions\") instanceof CompoundTag regionsTag)\n            regions = regionsTag.size();\n\n        return new LitematicFile(file, (CompoundTag) metadataTag,\n                ((IntTag) versionTag).getValue(),\n                root.getIntOrZero(\"SubVersion\"),\n                root.getIntOrZero(\"MinecraftDataVersion\"),\n                regions\n        );\n    }","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCLCore/src/main/java/org/jackhuang/hmcl/schematic/LitematicFile.java#L34-L70","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-export the litematic with the Litematica mod so Version is written as an NBT int.","Fix the generating script/tool to write Version as an NBT IntTag.","Re-download the file if it may be corrupted; verify it loads in Litematica in-game."],"exampleFix":"// before\nVersion: \"5\" (StringTag)\n// after\nVersion: 5 (IntTag)","handlingStrategy":"type-guard","validationCode":"Tag versionTag = root.get(\"Version\");\nif (!(versionTag instanceof IntTag))\n    throw new IOException(\"Version tag is not an integer\");","typeGuard":"if (versionTag instanceof IntTag intTag) {\n    int version = intTag.getValue(); // safe to use\n}","tryCatchPattern":"try {\n    LitematicFile.load(file);\n} catch (IOException e) {\n    if (e.getMessage().equals(\"Version tag is not an integer\")) {\n        // re-export the schematic or fix the writer tool\n    }\n}","preventionTips":["Write the Version field as an NBT IntTag in any custom litematic tooling.","Test custom NBT writers against real Litematica output.","Re-export schematics in-game rather than editing NBT by hand."],"tags":["schematic","litematic","nbt","type-mismatch"],"backgroundTag":"type-mismatch","analyzedSha":"24702dc5a0214034f4c27166d5fd30cad08cec19","analyzedAt":"2026-09-10T12:36:46.680Z","contentChangedAt":"2026-09-10T12:36:46.680Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}