{"record":{"id":"e2ffaca92df0ae53","repo":"HMCL-dev/HMCL","slug":"file-modfile-is-not-a-quilt-mod","errorCode":null,"errorMessage":"\"File \" + modFile + \" is not a Quilt mod.\"","messagePattern":"\"File \" \\+ modFile \\+ \" is not a Quilt mod\\.\"","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"HMCLCore/src/main/java/org/jackhuang/hmcl/addon/meta/QuiltModMetadata.java","lineNumber":77,"sourceCode":"        public QuiltLoader(String id, String version, Metadata metadata) {\n            this.id = id;\n            this.version = version;\n            this.metadata = metadata;\n        }\n    }\n\n    private final int schema_version;\n    private final QuiltLoader quilt_loader;\n\n    public QuiltModMetadata(int schemaVersion, QuiltLoader quiltLoader) {\n        this.schema_version = schemaVersion;\n        this.quilt_loader = quiltLoader;\n    }\n\n    public static LocalModFile fromFile(ModManager modManager, Path modFile, ZipFileTree tree) throws IOException, JsonParseException {\n        ZipArchiveEntry path = tree.getEntry(\"quilt.mod.json\");\n        if (path == null) {\n            throw new IOException(\"File \" + modFile + \" is not a Quilt mod.\");\n        }\n\n        QuiltModMetadata root = JsonUtils.fromNonNullJsonFully(tree.getInputStream(path), QuiltModMetadata.class);\n        if (root.schema_version != 1) {\n            throw new IOException(\"File \" + modFile + \" is not a supported Quilt mod.\");\n        }\n\n        return new LocalModFile(\n                modManager,\n                modManager.getLocalMod(root.quilt_loader.id, ModLoaderType.QUILT),\n                modFile,\n                root.quilt_loader.metadata.name,\n                new LocalAddonFile.Description(root.quilt_loader.metadata.description),\n                root.quilt_loader.metadata.contributors.entrySet().stream().map(entry -> String.format(\"%s (%s)\", entry.getKey(), entry.getValue().getAsJsonPrimitive().getAsString())).collect(Collectors.joining(\", \")),\n                root.quilt_loader.version,\n                \"\",\n                Optional.ofNullable(root.quilt_loader.metadata.contact.get(\"homepage\")).map(jsonElement -> jsonElement.getAsJsonPrimitive().getAsString()).orElse(\"\"),\n                root.quilt_loader.metadata.icon","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCLCore/src/main/java/org/jackhuang/hmcl/addon/meta/QuiltModMetadata.java#L59-L95","documentation":"This error in QuiltModMetadata.fromFile fires when the selected mod archive does not contain a quilt.mod.json entry. The input at fault is the mod file itself: without that descriptor the file cannot be a Quilt mod, so metadata loading fails with an IOException describing the file path.","triggerScenarios":"Calling QuiltModMetadata.fromFile with a ZipFileTree for a jar without `quilt.mod.json` (Fabric `fabric.mod.json`, Forge mods, or non-mod jars).","commonSituations":"Probing Fabric or Forge mods against the Quilt parser; jar missing metadata because it was built with a misconfigured build script.","solutions":["Check tree.getEntry(\"quilt.mod.json\") before calling fromFile","Use FabricModMetadata/Forge metadata parsers for non-Quilt mods","Rebuild the mod so quilt.mod.json is packaged at the jar root"],"exampleFix":"// before\nQuiltModMetadata.fromFile(modManager, modFile, tree);\n// after\nif (tree.getEntry(\"quilt.mod.json\") != null) {\n    QuiltModMetadata.fromFile(modManager, modFile, tree);\n}","handlingStrategy":"type-guard","validationCode":"if (tree.getEntry(\"quilt.mod.json\") == null) {\n    // not a Quilt mod; try fabric.mod.json etc.\n}","typeGuard":"boolean isQuiltMod(ZipFileTree tree) {\n    return tree.getEntry(\"quilt.mod.json\") != null;\n}","tryCatchPattern":"try {\n    QuiltModMetadata.fromFile(modManager, modFile, tree);\n} catch (IOException e) {\n    if (e.getMessage().contains(\"is not a Quilt mod\")) tryNextParser(modFile, tree);\n}","preventionTips":["Probe marker entries for each loader before choosing a parser","Check build config includes quilt.mod.json in processResources","Don't rely on file extension to determine mod loader"],"tags":["java","io","mod-metadata","quilt"],"backgroundTag":"resource-not-found","analyzedSha":"24702dc5a0214034f4c27166d5fd30cad08cec19","analyzedAt":"2026-09-10T12:36:46.680Z","contentChangedAt":"2026-09-10T12:36:46.680Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}