HMCL-dev/HMCL · error · JsonParseException

Unsupported os condition value:

Error message

Unsupported os condition value: 

What it means

normalizeOperatingSystemValue maps OS condition values to a known set and verifies membership in SUPPORTED_OS_VALUES. An OS value outside the supported set (after normalization) throws this JsonParseException.

Solutions

1. Replace the OS value with a supported token such as "windows", "linux", "macos", "freebsd", or "unknown".
2. Normalize aliases before writing the theme (e.g. map "win32"/"win" -> "windows").
3. Check the ThemeCondition source for the exact SUPPORTED_OS_VALUES set and match it.
4. Catch JsonParseException and display the supported OS values to the theme author.

Example fix

// before (theme.json)
// "os": ["win32"]
// after
"os": ["windows"]

java.util.Set<String> supported = java.util.Set.of("windows","linux","macos","freebsd","unknown");
boolean ok = supported.contains(os.trim().toLowerCase(java.util.Locale.ROOT));

static boolean isSupportedOsValue(String v) {
    String n = v == null ? "" : v.trim().toLowerCase(java.util.Locale.ROOT);
    return java.util.Set.of("windows","linux","macos","freebsd","unknown").contains(n);
}

try {
    ThemeCondition c = ThemeCondition.fromJson(element);
} catch (JsonParseException e) {
    LOG.warning("Unsupported OS condition value: " + e.getMessage());
}

When it happens

Trigger: ThemeCondition.fromJson reading {"os": ["android"]} or {"os": "win32"} — a value not among the supported tokens (e.g. windows/linux/macos/freebsd/unknown and their aliases).

Common situations: Theme authors using raw os.name values ("win32", "Windows 11") instead of the launcher's tokens; ported themes from other tools; new OS names not yet in the launcher's supported list.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unsupported brightness condition value:
• Theme condition array is empty:
• Theme condition array must contain strings:
• Theme condition value must be a string or string array:
• Theme condition key is blank

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemeCondition.java:199

            case KEY_OS -> normalizeOperatingSystemValue(normalized, value);
            case KEY_LANGUAGE -> normalized;
            default -> trimmed;
        };
    }

    /// Normalizes an operating system condition value.
    private static String normalizeOperatingSystemValue(String normalized, String original) {
        String value = switch (normalized) {
            case "win", "windows" -> "windows";
            case "mac", "macos", "osx" -> "macos";
            case "linux" -> "linux";
            case "freebsd" -> "freebsd";
            case "unknown", "universal" -> "unknown";
            default -> normalized;
        };

        if (!SUPPORTED_OS_VALUES.contains(value)) {
            throw new JsonParseException("Unsupported os condition value: " + original);
        }
        return value;
    }

}

View on GitHub (pinned to 24702dc5a0)