HMCL-dev/HMCL · error · IOException

Path cannot be recognized as a Minecraft world

Error message

Path  cannot be recognized as a Minecraft world

What it means

Thrown by the World(Path) constructor as the final else-branch: the given path is neither a directory containing level.dat nor a zip archive that resolves to level.dat/special_level.dat. It means HMCL could not recognize the path as any supported form of a Minecraft world.

Solutions

1. Pass the path of a single world directory that directly contains level.dat, not the saves directory itself
2. If passing a zip, confirm it contains level.dat at root or in exactly one top-level subfolder
3. Check the path exists and the spelling is correct (Files.exists)
4. Re-copy the world from a working Minecraft installation so level.dat is present

Example fix

// before
World world = new World(Path.of(".minecraft/saves")); // parent dir, no level.dat
// after
World world = new World(Path.of(".minecraft/saves/New World")); // world dir with level.dat

static Path requireWorldPath(Path p) throws IOException {
    if (Files.isDirectory(p) && Files.isRegularFile(p.resolve("level.dat"))) return p;
    if (Files.isRegularFile(p)) return p; // delegate zip layout checks to World
    throw new IOException("Not a world directory (missing level.dat) or file: " + p);
}

static boolean isWorldDirectory(Path p) {
    return Files.isDirectory(p) && Files.isRegularFile(p.resolve("level.dat"));
}

try {
    World world = new World(path);
} catch (IOException e) {
    if (String.valueOf(e.getMessage()).contains("cannot be recognized as a Minecraft world")) {
        // show user the path and ask for a valid world folder or zip
    }
}

When it happens

Trigger: new World(path) where path is a directory without level.dat, a file whose zip lacks level.dat, or a path that is neither a regular file nor a directory (e.g. nonexistent path on some filesystems).

Common situations: Pointing HMCL at the parent 'saves' folder instead of a single world folder, typos in the world directory name, passing a .mcpack/.rar or other unsupported archive, or a world folder missing level.dat after a bad copy.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• Not a valid world zip file since level.dat or…
• Not a valid world directory
• World already exists
• The world has been locked
• Theme-pack asset entry must be relative:

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/game/World.java:123

                }
                if (!Files.exists(levelDat)) {
                    throw new IOException("Not a valid world zip file since level.dat or special_level.dat cannot be found.");
                }
                loadAndCheckLevelData(levelDat);

                Path iconFile = root.resolve("icon.png");
                if (Files.isRegularFile(iconFile)) {
                    try (InputStream inputStream = Files.newInputStream(iconFile)) {
                        icon = new Image(inputStream, 64, 64, true, false);
                        if (icon.isError())
                            throw icon.getException();
                    } catch (Exception e) {
                        LOG.warning("Failed to load world icon", e);
                    }
                }
            }
        else
            throw new IOException("Path " + file + " cannot be recognized as a Minecraft world");
    }

    public Path getFile() {
        return file;
    }

    public String getFileName() {
        return fileName;
    }

    public String getWorldName() {
        if (levelData.get("Data") instanceof CompoundTag data
                && data.get("LevelName") instanceof StringTag levelNameTag)
            return levelNameTag.get();
        else
            return "";
    }

View on GitHub (pinned to 24702dc5a0)