HMCL-dev/HMCL · error · JsonParseException

Theme-pack authors must be an array

Error message

Theme-pack authors must be an array

What it means

parseAuthors parses the theme pack 'authors' field. A null element is treated as no authors, but if the element is present and is not a JSON array, JsonParseException("Theme-pack authors must be an array") is thrown. Authors are always a list in the schema.

Solutions

1. Change the authors field to a JSON array, e.g. "authors": ["Alice"]
2. If a single author, wrap it: "authors": ["value"]
3. Validate the theme pack JSON against the schema before loading

Example fix

// before
"authors": "Alice"
// after
"authors": ["Alice"]

static boolean isValidAuthors(JsonElement e) {
    return e == null || e.isJsonNull() || e.isJsonArray();
}

static boolean isJsonArrayOrNull(JsonElement e) {
    return e == null || e instanceof JsonArray;
}

try {
    List<ThemePackAuthor> authors = parseAuthors(el.get("authors"));
} catch (JsonParseException e) {
    log.warn("Ignoring invalid authors field: " + e.getMessage());
}

When it happens

Trigger: Calling parseAuthors (via theme pack parsing) where the 'authors' field is a string (e.g. "authors": "Alice"), an object, or a number instead of an array.

Common situations: Theme pack authors write a single author as a plain string instead of ["Alice"], or an older/other tool emitted a different shape.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Theme-pack manifest must declare exactly one of theme or…
• Theme color must be a string or object
• Invalid theme override
• Theme override must define an object condition
• Theme-pack author must be an object or a string

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/theme/ThemePackAuthor.java:50

import static org.jackhuang.hmcl.util.logging.Logger.LOG;

/// Author metadata declared by a theme pack.
///
/// @param name the localized author display name
@NotNullByDefault
@JsonSerializable
@JsonAdapter(ThemePackAuthor.Adapter.class)
public record ThemePackAuthor(LocalizedText name) {

    /// Parses author metadata from a JSON array.
    static @Unmodifiable List<ThemePackAuthor> parseAuthors(@Nullable JsonElement element) throws JsonParseException {
        if (element == null || element.isJsonNull()) {
            return List.of();
        }

        if (!(element instanceof JsonArray jsonArray)) {
            throw new JsonParseException("Theme-pack authors must be an array");
        }

        ArrayList<ThemePackAuthor> authors = new ArrayList<>(jsonArray.size());
        int index = 0;
        for (JsonElement authorJson : jsonArray) {
            try {
                ThemePackAuthor author = fromJson(authorJson);
                if (author != null) {
                    authors.add(author);
                }
            } catch (JsonParseException | IllegalArgumentException e) {
                LOG.warning("Ignored invalid theme-pack author at authors[" + index + "]: " + authorJson, e);
            }
            index++;
        }

        return List.copyOf(authors);
    }

View on GitHub (pinned to 24702dc5a0)