What causes "Empty theme condition context value: ${name}" in HMCL-dev/HMCL?

Supply a concrete non-blank value for the named context key when constructing ThemeResolveContext.

HMCL-dev/HMCL · error · IllegalArgumentException

Empty theme condition context value

Error message

Empty theme condition context value: ${name}

What it means

ThemeResolveContext.normalizeToken lowercases and trims a condition context token (e.g. language, platform values used in theme conditional expressions); if the normalized value is empty it throws IllegalArgumentException "Empty theme condition context value: <name>". Condition matching requires non-empty tokens so rules always evaluate against concrete values.

Solutions

Supply a concrete non-blank value for the named context key when constructing ThemeResolveContext.
Add a default (e.g. "unknown" or "en") when the underlying setting may be empty.
Check where the value originates (system property/env) and fix the source that yields the blank string.

Example fix

// before
ctx = new ThemeResolveContext(lang, "")
// after
ctx = new ThemeResolveContext(lang.isBlank() ? "en" : lang, osName)

Defensive patterns

Strategy: validation

Validate before calling

String safe = value == null ? null : value.trim().toLowerCase(Locale.ROOT); boolean ok = safe != null && !safe.isEmpty();

Try / catch

try { ctx = new ThemeResolveContext(values); } catch (IllegalArgumentException e) { ctx = defaultContext(); }

Prevention

Default empty env/system values to a known token like "unknown"
Normalize and check tokens at the call site
Never pass optional lookups straight into context construction

When it happens

Trigger: Building a ThemeResolveContext with an empty or whitespace-only value for a named context key; a system property or environment lookup that returned "" for language/OS tokens.

Common situations: Environment variables or settings that are defined but empty; refactored code passing an optional value straight through without a default; localized system reports with blank locale fields.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemeResolveContext.java:90

    }

    /// Returns the normalized name for an operating system.
    ///
    /// @param operatingSystem the operating system to normalize
    /// @return the normalized operating system name
    static String normalizeOperatingSystem(OperatingSystem operatingSystem) {
        Objects.requireNonNull(operatingSystem);

        return operatingSystem == OperatingSystem.UNKNOWN ? "unknown" : operatingSystem.getCheckedName();
    }

    /// Normalizes one condition context token.
    private static String normalizeToken(String value, String name) {
        Objects.requireNonNull(value, name);

        String normalized = value.trim().toLowerCase(Locale.ROOT);
        if (normalized.isEmpty()) {
            throw new IllegalArgumentException("Empty theme condition context value: " + name);
        }
        return normalized;
    }
}

View on GitHub (pinned to 24702dc5a0)