{"record":{"id":"437b8d5ed2a167c5","repo":"HMCL-dev/HMCL","slug":"version-tag-not-found","errorCode":null,"errorMessage":"Version tag not found","messagePattern":"Version tag not found","errorType":"exception","errorClass":"java.io.IOException","httpStatus":null,"severity":"error","filePath":"HMCLCore/src/main/java/org/jackhuang/hmcl/schematic/LitematicFile.java","lineNumber":50,"sourceCode":"\n/// @author Glavo\n/// @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","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCLCore/src/main/java/org/jackhuang/hmcl/schematic/LitematicFile.java#L32-L68","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the file is a genuine .litematic created by the Litematica mod; re-export it from the game.","Re-download the schematic file — it may be truncated or corrupted.","Convert other schematic formats (e.g. .schem) to .litematic with a converter tool before loading."],"exampleFix":"// before: NBT root lacks Version\n{\"Metadata\": {...}, \"Regions\": {...}}\n// after (valid litematic root)\n{\"Version\": 5, \"MinecraftDataVersion\": 3465, \"Metadata\": {...}, \"Regions\": {...}}","handlingStrategy":"validation","validationCode":"NBT root = readRoot(file);\nif (root == null || !root.containsKey(\"Version\"))\n    throw new IOException(\"not a valid litematic: missing Version tag\");","typeGuard":null,"tryCatchPattern":"try {\n    LitematicFile.load(file);\n} catch (IOException e) {\n    if (e.getMessage().equals(\"Version tag not found\")) {\n        // file is not a valid litematic; convert or re-export it\n    }\n}","preventionTips":["Only load .litematic files created by the Litematica mod.","Check file integrity after downloading schematics.","Convert WorldEdit/structure NBT files to litematic format first."],"tags":["schematic","litematic","nbt","missing-field"],"backgroundTag":"schema-validation-failed","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"}