{"record":{"id":"6bae805e792f2eac","repo":"HMCL-dev/HMCL","slug":"file-modfile-is-not-a-supported-quilt-mod","errorCode":null,"errorMessage":"\"File \" + modFile + \" is not a supported Quilt mod.\"","messagePattern":"\"File \" \\+ modFile \\+ \" is not a supported Quilt mod\\.\"","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"HMCLCore/src/main/java/org/jackhuang/hmcl/addon/meta/QuiltModMetadata.java","lineNumber":82,"sourceCode":"    }\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\n        );\n    }\n}\n","sourceCodeStart":64,"sourceCodeEnd":99,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCLCore/src/main/java/org/jackhuang/hmcl/addon/meta/QuiltModMetadata.java#L64-L99","documentation":"This error in QuiltModMetadata.fromFile fires when quilt.mod.json exists in the archive but cannot be parsed into a valid QuiltModMetadata (e.g. missing required schema_version or quilt_loader fields, or invalid JSON). The file is recognizably a Quilt mod but its metadata is unsupported or malformed.","triggerScenarios":"Calling QuiltModMetadata.fromFile on a jar whose quilt.mod.json declares schema_version other than 1 (future Quilt formats or a typo'd/missing schema_version field).","commonSituations":"Mods built against a newer Quilt metadata spec than this parser supports; hand-written quilt.mod.json omitting or mistyping schema_version.","solutions":["Set \"schema_version\": 1 in quilt.mod.json","Upgrade HMCL/HMCLCore to a version supporting newer schema versions","Check the mod's required Quilt loader compatibility"],"exampleFix":"// before\n{ \"schema_version\": 2, \"quilt_loader\": { ... } }\n// after\n{ \"schema_version\": 1, \"quilt_loader\": { ... } }","handlingStrategy":"validation","validationCode":"JsonObject root = JsonParser.parseString(readEntry(tree, \"quilt.mod.json\")).getAsJsonObject();\nif (root.get(\"schema_version\") == null || root.get(\"schema_version\").getAsInt() != 1)\n    throw new IllegalStateException(\"unsupported schema_version\");","typeGuard":null,"tryCatchPattern":"try {\n    QuiltModMetadata.fromFile(modManager, modFile, tree);\n} catch (IOException e) {\n    if (e.getMessage().contains(\"not a supported Quilt mod\"))\n        log.warn(\"Unsupported quilt.mod.json schema in \" + modFile);\n}","preventionTips":["Pin schema_version to 1 in quilt.mod.json","Keep HMCL updated for newer schema support","Document the supported schema in the mod's contributor docs"],"tags":["java","mod-metadata","quilt","version-incompatibility"],"backgroundTag":"unsupported-config-value","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"}