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

Metadata tag not found

Error message

Metadata tag not found

What it means

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.).

Solutions

1. Verify the file is a genuine litematic file saved by the Litematica mod and not another schematic format
2. Re-export or re-download the litematic file to rule out corruption
3. Inspect the file's root NBT compound (e.g. with NBTExplorer) and confirm a 'Metadata' compound exists
4. Add a pre-check in calling code that reads the root tag and validates required keys before invoking load

Example fix

// before
LitematicFile file = LitematicFile.load(path);
// after
CompoundTag root = NBTUtil.readRoot(path);
if (root.getValue().get("Metadata") == null)
    throw new IllegalArgumentException("Not a litematic file: missing Metadata tag");
LitematicFile file = LitematicFile.load(path);

CompoundTag root = NBTUtil.readRoot(path);
if (!(root.getValue().get("Metadata") instanceof CompoundTag))
    throw new IllegalArgumentException("File is not a valid litematic: missing Metadata");

static boolean isLitematicRoot(CompoundTag root) {
    return root != null && root.getValue().get("Metadata") instanceof CompoundTag;
}

try {
    LitematicFile f = LitematicFile.load(path);
} catch (IOException e) {
    if (e.getMessage().contains("Metadata tag not found")) showCorruptFileDialog();
    else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Metadata tag is not a compound tag
• Version tag is not an integer
• Version tag not found
• Asset index file malformed
• Bad exit code

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

Appendix: source

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

        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
        );
    }

    private final @NotNull Path file;

    private final int version;

View on GitHub (pinned to 24702dc5a0)