HMCL-dev/HMCL · error · IOException

"File " + modFile + " is not a supported Quilt mod."

Error message

"File " + modFile + " is not a supported Quilt mod."

What it means

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.

Solutions

  1. Set "schema_version": 1 in quilt.mod.json
  2. Upgrade HMCL/HMCLCore to a version supporting newer schema versions
  3. Check the mod's required Quilt loader compatibility

Example fix

// before
{ "schema_version": 2, "quilt_loader": { ... } }
// after
{ "schema_version": 1, "quilt_loader": { ... } }
Defensive patterns

Strategy: validation

Validate before calling

JsonObject root = JsonParser.parseString(readEntry(tree, "quilt.mod.json")).getAsJsonObject();
if (root.get("schema_version") == null || root.get("schema_version").getAsInt() != 1)
    throw new IllegalStateException("unsupported schema_version");

Try / catch

try {
    QuiltModMetadata.fromFile(modManager, modFile, tree);
} catch (IOException e) {
    if (e.getMessage().contains("not a supported Quilt mod"))
        log.warn("Unsupported quilt.mod.json schema in " + modFile);
}

Prevention

When it happens

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

Common situations: Mods built against a newer Quilt metadata spec than this parser supports; hand-written quilt.mod.json omitting or mistyping schema_version.

Related errors

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/addon/meta/QuiltModMetadata.java:82

    }

    private final int schema_version;
    private final QuiltLoader quilt_loader;

    public QuiltModMetadata(int schemaVersion, QuiltLoader quiltLoader) {
        this.schema_version = schemaVersion;
        this.quilt_loader = quiltLoader;
    }

    public static LocalModFile fromFile(ModManager modManager, Path modFile, ZipFileTree tree) throws IOException, JsonParseException {
        ZipArchiveEntry path = tree.getEntry("quilt.mod.json");
        if (path == null) {
            throw new IOException("File " + modFile + " is not a Quilt mod.");
        }

        QuiltModMetadata root = JsonUtils.fromNonNullJsonFully(tree.getInputStream(path), QuiltModMetadata.class);
        if (root.schema_version != 1) {
            throw new IOException("File " + modFile + " is not a supported Quilt mod.");
        }

        return new LocalModFile(
                modManager,
                modManager.getLocalMod(root.quilt_loader.id, ModLoaderType.QUILT),
                modFile,
                root.quilt_loader.metadata.name,
                new LocalAddonFile.Description(root.quilt_loader.metadata.description),
                root.quilt_loader.metadata.contributors.entrySet().stream().map(entry -> String.format("%s (%s)", entry.getKey(), entry.getValue().getAsJsonPrimitive().getAsString())).collect(Collectors.joining(", ")),
                root.quilt_loader.version,
                "",
                Optional.ofNullable(root.quilt_loader.metadata.contact.get("homepage")).map(jsonElement -> jsonElement.getAsJsonPrimitive().getAsString()).orElse(""),
                root.quilt_loader.metadata.icon
        );
    }
}

View on GitHub (pinned to 24702dc5a0)