{"record":{"id":"d89f62afd72dd515","repo":"HMCL-dev/HMCL","slug":"path-cannot-be-recognized-as-a-minecraft-world","errorCode":null,"errorMessage":"Path  cannot be recognized as a Minecraft world","messagePattern":"Path  cannot be recognized as a Minecraft world","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"HMCLCore/src/main/java/org/jackhuang/hmcl/game/World.java","lineNumber":123,"sourceCode":"                }\n                if (!Files.exists(levelDat)) {\n                    throw new IOException(\"Not a valid world zip file since level.dat or special_level.dat cannot be found.\");\n                }\n                loadAndCheckLevelData(levelDat);\n\n                Path iconFile = root.resolve(\"icon.png\");\n                if (Files.isRegularFile(iconFile)) {\n                    try (InputStream inputStream = Files.newInputStream(iconFile)) {\n                        icon = new Image(inputStream, 64, 64, true, false);\n                        if (icon.isError())\n                            throw icon.getException();\n                    } catch (Exception e) {\n                        LOG.warning(\"Failed to load world icon\", e);\n                    }\n                }\n            }\n        else\n            throw new IOException(\"Path \" + file + \" cannot be recognized as a Minecraft world\");\n    }\n\n    public Path getFile() {\n        return file;\n    }\n\n    public String getFileName() {\n        return fileName;\n    }\n\n    public String getWorldName() {\n        if (levelData.get(\"Data\") instanceof CompoundTag data\n                && data.get(\"LevelName\") instanceof StringTag levelNameTag)\n            return levelNameTag.get();\n        else\n            return \"\";\n    }\n","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCLCore/src/main/java/org/jackhuang/hmcl/game/World.java#L105-L141","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Pass the path of a single world directory that directly contains level.dat, not the saves directory itself","If passing a zip, confirm it contains level.dat at root or in exactly one top-level subfolder","Check the path exists and the spelling is correct (Files.exists)","Re-copy the world from a working Minecraft installation so level.dat is present"],"exampleFix":"// before\nWorld world = new World(Path.of(\".minecraft/saves\")); // parent dir, no level.dat\n// after\nWorld world = new World(Path.of(\".minecraft/saves/New World\")); // world dir with level.dat","handlingStrategy":"validation","validationCode":"static Path requireWorldPath(Path p) throws IOException {\n    if (Files.isDirectory(p) && Files.isRegularFile(p.resolve(\"level.dat\"))) return p;\n    if (Files.isRegularFile(p)) return p; // delegate zip layout checks to World\n    throw new IOException(\"Not a world directory (missing level.dat) or file: \" + p);\n}","typeGuard":"static boolean isWorldDirectory(Path p) {\n    return Files.isDirectory(p) && Files.isRegularFile(p.resolve(\"level.dat\"));\n}","tryCatchPattern":"try {\n    World world = new World(path);\n} catch (IOException e) {\n    if (String.valueOf(e.getMessage()).contains(\"cannot be recognized as a Minecraft world\")) {\n        // show user the path and ask for a valid world folder or zip\n    }\n}","preventionTips":["Pass a single world folder (saves/<WorldName>), not the saves directory itself","Verify level.dat exists in the folder before constructing World","Only use .zip archives; formats like .rar/.7z are not supported by CompressingUtils autodetection paths","Check the path exists after any move/sync operation"],"tags":["minecraft","io","world-import","path"],"backgroundTag":"incompatible-source-type","analyzedSha":"24702dc5a0214034f4c27166d5fd30cad08cec19","analyzedAt":"2026-09-10T12:36:46.680Z","contentChangedAt":"2026-09-10T12:36:46.680Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}