{"record":{"id":"6e98e520c193d088","repo":"HMCL-dev/HMCL","slug":"metadata-tag-not-found","errorCode":null,"errorMessage":"Metadata tag not found","messagePattern":"Metadata 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":56,"sourceCode":"        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    }\n\n    private final @NotNull Path file;\n\n    private final int version;","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCLCore/src/main/java/org/jackhuang/hmcl/schematic/LitematicFile.java#L38-L74","documentation":"LitematicFile.load() parses a litematic NBT file and requires the root compound to contain a 'Metadata' tag. This IOException is thrown when the 'Metadata' key is absent from the root NBT compound, since the loader cannot construct a LitematicFile without its metadata (name, size, etc.).","triggerScenarios":"Calling LitematicFile.load(file) on an NBT file whose root CompoundTag has no 'Metadata' entry — e.g. a corrupted, truncated, or hand-crafted litematic file, or an entirely different NBT format (schem, structure block) being loaded as a litematic.","commonSituations":"Pointing the loader at a .schem or .litematic file saved by a different tool/version that omitted Metadata; a partially downloaded or corrupted file; mistakenly loading a schematic from another mod.","solutions":["Verify the file is a genuine litematic file saved by the Litematica mod and not another schematic format","Re-export or re-download the litematic file to rule out corruption","Inspect the file's root NBT compound (e.g. with NBTExplorer) and confirm a 'Metadata' compound exists","Add a pre-check in calling code that reads the root tag and validates required keys before invoking load"],"exampleFix":"// before\nLitematicFile file = LitematicFile.load(path);\n// after\nCompoundTag root = NBTUtil.readRoot(path);\nif (root.getValue().get(\"Metadata\") == null)\n    throw new IllegalArgumentException(\"Not a litematic file: missing Metadata tag\");\nLitematicFile file = LitematicFile.load(path);","handlingStrategy":"validation","validationCode":"CompoundTag root = NBTUtil.readRoot(path);\nif (!(root.getValue().get(\"Metadata\") instanceof CompoundTag))\n    throw new IllegalArgumentException(\"File is not a valid litematic: missing Metadata\");","typeGuard":"static boolean isLitematicRoot(CompoundTag root) {\n    return root != null && root.getValue().get(\"Metadata\") instanceof CompoundTag;\n}","tryCatchPattern":"try {\n    LitematicFile f = LitematicFile.load(path);\n} catch (IOException e) {\n    if (e.getMessage().contains(\"Metadata tag not found\")) showCorruptFileDialog();\n    else throw e;\n}","preventionTips":["Validate NBT root keys before calling load","Only feed files with the .litematic extension saved by Litematica","Checksum downloaded litematic files against source hashes"],"tags":["nbt","litematic","missing-tag","io"],"backgroundTag":"missing-required-argument","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"}