HMCL-dev/HMCL · error · JsonParseException

Artifact name is malformed

Error message

Artifact name is malformed

What it means

Thrown (as a JsonParseException caused by IllegalArgumentException from Artifact.fromDescriptor) when the library deserializes a Maven-artifact-style coordinate string for a library/download entry and the string does not split into the expected groupId:artifactId:version[@classifier@ext] parts. HMCL uses this to parse 'libraries' entries in version JSON files, so a malformed coordinate means the version metadata itself is broken.

Solutions

1. Open the version JSON (versions/<id>/<id>.json) and fix the malformed library 'name' string to the full groupId:artifactId:version[:classifier] format
2. Re-download the version JSON from its source (launcher metadata / Mojang) instead of hand-editing
3. If generating JSON yourself, validate each library name matches ^[^:]+:[^:]+:[^:]+(?:[^:]*)? before writing
4. Catch JsonParseException when parsing third-party version metadata and surface the offending library name to the user

Example fix

// before
"name": "org.lwjgl"
// after
"name": "org.lwjgl:lwjgl:3.3.1"

static boolean isValidArtifactName(String name) {
    return name != null && name.matches("[^:]+:[^:]+:[^:]+.*");
}
// check each library entry before feeding it to the parser

boolean validDescriptor = s != null && s.chars().filter(c -> c == ':').count() >= 2;

try {
    Artifact a = artifactAdapter.parse(json);
} catch (JsonParseException e) {
    LOG.warning("Skipping malformed library descriptor: " + e.getCause().getMessage());
    continue;
}

When it happens

Trigger: Calling the Artifact Gson TypeAdapter's read() on JSON whose string value lacks the required colon-separated segments (e.g. 'my-lib' or 'a:b:' instead of 'net.foo:my-lib:1.0'), or manually constructing an artifact descriptor with wrong syntax via Artifact.fromDescriptor.

Common situations: Hand-edited or third-party version JSONs with truncated library names; corrupted download of the version json; copying a Gradle dependency notation with extras like 'net.foo:lib:1.0@jar ' trailing data the parser rejects; custom forks generating library lists programmatically.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Malformed response
• json.toString()
• json.toString()
• e
• Account private data is not an object

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/game/Artifact.java:143

    @Override
    public String toString() {
        return descriptor;
    }

    public static final class Adapter extends TypeAdapter<@Nullable Artifact> {

        @Override
        public @Nullable Artifact read(JsonReader in) throws IOException {
            if (in.peek() == JsonToken.NULL) {
                in.nextNull();
                return null;
            }

            try {
                return fromDescriptor(in.nextString());
            } catch (IllegalArgumentException e) {
                throw new JsonParseException(e);
            }
        }

        @Override
        public void write(JsonWriter out, @Nullable Artifact value) throws IOException {
            if (value == null) {
                out.nullValue();
            } else {
                out.value(value.toString());
            }
        }
    }
}

View on GitHub (pinned to 24702dc5a0)