HMCL-dev/HMCL · error · IllegalArgumentException

Expected typed ID prefix '" + expectedPrefix + "'

Error message

Expected typed ID prefix '" + expectedPrefix + "'

What it means

TypedID.parseUUID parses a string that must begin with a fixed type prefix (e.g. "profile:") followed by a UUID. This IllegalArgumentException is thrown when the value does not start with the expected prefix plus separator, so the remaining substring would not be a bare UUID.

Solutions

1. Ensure the stored/serialized ID string includes the correct prefix and separator before calling parseUUID.
2. Check which prefix constant the ID was created with and pass the matching one to parseUUID.
3. If the value may be unprefixed, normalize it first (prepend the prefix) or handle the IllegalArgumentException.
4. Verify the data source (config file, server response) is not emitting plain UUIDs.

Example fix

// before
UUID id = TypedID.parseUUID("profile", rawId); // throws if rawId has no prefix
// after
if (!rawId.startsWith("profile" + TypedID.getSeparator())) {
    rawId = "profile" + TypedID.getSeparator() + rawId;
}
UUID id = TypedID.parseUUID("profile", rawId);

if (value == null || !value.startsWith(prefix + TypedID.getSeparator()))
    throw new IllegalArgumentException("Not a typed ID with prefix " + prefix + ": " + value);

static boolean isTypedID(String prefix, String value) {
    return value != null && value.startsWith(prefix + TypedID.getSeparator());
}

try {
    UUID id = TypedID.parseUUID(prefix, value);
} catch (IllegalArgumentException e) {
    log.warn("Malformed typed ID: {}", value, e);
}

When it happens

Trigger: Calling TypedID.parseUUID(prefix, value) where value lacks the `prefix + SEPARATOR` prefix, e.g. parsing a raw UUID string or a value typed with a different prefix.

Common situations: Storing legacy IDs without the typed prefix, reading IDs written by an older HMCL version, or mixing up prefix constants (passing an account ID where a profile ID is expected).

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Artifact name is malformed
• Bad Build-Number
• Empty components.
• "File '" + file + "' is not a resource pack"
• "File " + file + " is not a valid mod file."

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

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/util/TypedID.java:65

    static String format(String prefix, UUID uuid) {
        Objects.requireNonNull(prefix);
        Objects.requireNonNull(uuid);
        return prefix + SEPARATOR + uuid;
    }

    /// Parses the UUID payload from a typed ID string.
    ///
    /// @param prefix the required type prefix
    /// @param value the serialized typed ID
    /// @return the UUID payload
    /// @throws IllegalArgumentException if the value does not have the required prefix or UUID payload
    static UUID parseUUID(String prefix, String value) {
        Objects.requireNonNull(prefix);
        Objects.requireNonNull(value);

        String expectedPrefix = prefix + SEPARATOR;
        if (!value.startsWith(expectedPrefix)) {
            throw new IllegalArgumentException("Expected typed ID prefix '" + expectedPrefix + "'");
        }

        return UUIDs.parse(value.substring(expectedPrefix.length()));
    }

    /// Gson adapter for typed IDs with a fixed prefix.
    abstract class Adapter<T extends TypedID> extends TypeAdapter<@Nullable T> {
        /// The serialized ID prefix accepted by this adapter.
        private final String prefix;

        /// Factory creating typed IDs from parsed UUID payloads.
        private final Function<UUID, T> factory;

        /// Creates an adapter for typed IDs with the given prefix.
        ///
        /// @param prefix the serialized ID prefix
        /// @param factory creates the typed ID from the UUID payload
        protected Adapter(String prefix, Function<UUID, T> factory) {

View on GitHub (pinned to 24702dc5a0)