{"record":{"id":"2f701757419d4378","repo":"HMCL-dev/HMCL","slug":"metadata-tag-is-not-a-compound-tag","errorCode":null,"errorMessage":"Metadata tag is not a compound tag","messagePattern":"Metadata tag is not a compound tag","errorType":"exception","errorClass":"java.io.IOException","httpStatus":null,"severity":"error","filePath":"HMCLCore/src/main/java/org/jackhuang/hmcl/schematic/LitematicFile.java","lineNumber":58,"sourceCode":"\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;\n    private final int subVersion;\n    private final int minecraftDataVersion;","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCLCore/src/main/java/org/jackhuang/hmcl/schematic/LitematicFile.java#L40-L76","documentation":"LitematicFile.load() requires the root 'Metadata' tag to be a CompoundTag. This IOException is thrown when a 'Metadata' key exists in the root NBT compound but holds a different tag type (e.g. IntTag, StringTag), making the metadata unusable as a compound.","triggerScenarios":"Calling LitematicFile.load(file) on an NBT file where the root's 'Metadata' entry is present but is not a compound — usually from a malformed or tampered file, or an NBT writer that serialized metadata with the wrong type.","commonSituations":"Hand-edited litematic files; files produced by buggy third-party converters; corruption that overwrote tag types while keeping key names.","solutions":["Re-export or re-download the litematic file from a trusted source","Inspect the NBT tree and confirm 'Metadata' is a compound with expected sub-tags (Name, RegionCount, etc.)","Handle the IOException in calling code and surface a 'corrupted file' message to users","If the file was converted by a tool, fix the converter so it writes Metadata as a CompoundTag"],"exampleFix":"// before\nLitematicFile f = LitematicFile.load(path); // throws on malformed Metadata\n// after\ntry {\n    LitematicFile f = LitematicFile.load(path);\n} catch (IOException e) {\n    LOG.warning(\"Invalid litematic file: \" + e.getMessage());\n}","handlingStrategy":"validation","validationCode":"Object metadata = root.getValue().get(\"Metadata\");\nif (metadata != null && !(metadata instanceof CompoundTag))\n    throw new IllegalArgumentException(\"Metadata tag has wrong NBT type\");","typeGuard":"static boolean hasCompoundMetadata(CompoundTag root) {\n    return root.getValue().get(\"Metadata\") instanceof CompoundTag;\n}","tryCatchPattern":"try {\n    LitematicFile f = LitematicFile.load(path);\n} catch (IOException e) {\n    if (e.getMessage().contains(\"not a compound tag\")) showCorruptFileDialog();\n    else throw e;\n}","preventionTips":["Inspect NBT tag types after edits, not just key presence","Avoid hand-editing litematic NBT files; re-export instead","Validate converted files with NBTExplorer before distribution"],"tags":["nbt","litematic","type-mismatch","io"],"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"}