HMCL-dev/HMCL · error · IllegalArgumentException

Theme-pack asset entry must be a file:

Error message

Theme-pack asset entry must be a file:

What it means

A theme-pack asset entry must point to a file, not a directory: a normalized name ending in '/' throws IllegalArgumentException("Theme-pack asset entry must be a file: <name>"). Directory entries cannot identify an asset.

Solutions

  1. Remove the trailing slash and point to the concrete file, e.g. assets/icons/logo.png
  2. Skip directory entries when iterating pack contents (check entry.isDirectory())
  3. Fix the config value to a file path

Example fix

// before
for (entry : zip.entries()) use(entry.name()); // includes dirs
// after
for (entry : zip.entries()) { if (!entry.isDirectory()) use(entry.name()); }
Defensive patterns

Strategy: validation

Validate before calling

static boolean isFileEntry(ZipEntry e) {
    return !e.isDirectory();
}

Type guard

static boolean isFilePath(String n) {
    return !n.endsWith("/");
}

Try / catch

try {
    ThemePackAsset.of(entryName);
} catch (IllegalArgumentException e) {
    log.warn("Ignoring directory entry: " + e.getMessage());
}

Prevention

When it happens

Trigger: Passing entry names like "assets/icons/" or "assets/" to ThemePackAsset / normalizeEntryName.

Common situations: Iterating all ZIP entries and accidentally feeding directory entries into the asset resolver, or a config value with a trailing slash.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackAsset.java:71

    ///
    /// @param entryName the entry name to validate
    /// @return the normalized entry name
    /// @throws IllegalArgumentException if the entry name is unsafe or outside `assets/`
    static String normalizeEntryName(String entryName) {
        Objects.requireNonNull(entryName);

        String normalized = entryName.trim().replace('\\', '/');
        if (normalized.isEmpty()) {
            throw new IllegalArgumentException("Theme-pack asset entry is empty");
        }
        if (normalized.startsWith("/") || normalized.matches("^[A-Za-z]:.*")) {
            throw new IllegalArgumentException("Theme-pack asset entry must be relative: " + entryName);
        }
        if (!normalized.startsWith(ASSETS_PREFIX)) {
            throw new IllegalArgumentException("Theme-pack asset entry must be under assets/: " + entryName);
        }
        if (normalized.endsWith("/")) {
            throw new IllegalArgumentException("Theme-pack asset entry must be a file: " + entryName);
        }

        for (String segment : normalized.split("/")) {
            if (segment.isEmpty() || ".".equals(segment) || "..".equals(segment)) {
                throw new IllegalArgumentException("Theme-pack asset entry contains an unsafe segment: " + entryName);
            }
            for (int i = 0; i < segment.length(); i++) {
                char ch = segment.charAt(i);
                if (Character.isISOControl(ch) || ch == '\0') {
                    throw new IllegalArgumentException("Theme-pack asset entry contains a control character: " + entryName);
                }
            }
        }
        return normalized;
    }
}

View on GitHub (pinned to 24702dc5a0)