HMCL-dev/HMCL · error · JsonParseException

authlib-injectors.json -> urls cannot be null.

Error message

authlib-injectors.json -> urls cannot be null.

What it means

AuthlibInjectorServers.validate enforces that the parsed authlib-injectors.json config contains a non-null "urls" array, throwing JsonParseException when it is null. This validation runs when HMCL loads or installs the authlib injector server list, guaranteeing the rest of the code can safely iterate the URLs.

Solutions

1. Add the required "urls" array to authlib-injectors.json, e.g. {"urls": ["https://authserver.example.com/api/yggdrasil"]}
2. Delete the broken file so HMCL regenerates/ignores it, then re-add servers via the UI or -Dhmcl.authlib_injector_url parameter
3. Validate the JSON with a quick script (check json.urls is a non-null array) before shipping the file in your distribution
4. If generating the file programmatically, always serialize the urls field even when empty

Example fix

// before
{ "name": "Example Server" }
// after
{ "name": "Example Server", "urls": ["https://authserver.example.com/api/yggdrasil"] }

JsonObject cfg = JsonParser.parseString(Files.readString(authlibInjectorsPath)).getAsJsonObject();
if (!cfg.has("urls") || !cfg.get("urls").isJsonArray())
    throw new IOException("authlib-injectors.json must contain a urls array");

static boolean hasValidUrls(JsonObject cfg) {
    return cfg.has("urls") && cfg.get("urls").isJsonArray();
}

try {
    AuthlibInjectorServers.init();
} catch (JsonParseException e) {
    LOGGER.warning("Invalid authlib-injectors.json: " + e.getMessage());
    // regenerate or ignore the file and continue with no servers
}

When it happens

Trigger: Loading or saving authlib-injectors.json whose JSON object has no "urls" key (or an explicit null) followed by a validate() call — e.g. during AuthlibInjectorServers.init() reading the config location, or deserializing a server entry from command-line/config input.

Common situations: Hand-edited or truncated authlib-injectors.json missing the urls array; a launcher distribution tool writes the file with only metadata; a tool expecting a different schema writes {"server": ...} without urls.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Missing protected payload member: protection
• code is null
• profiles is null
• Account private data is not an object
• Game directory ID cannot be null

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/setting/AuthlibInjectorServers.java:62

    public static final String CONFIG_FILENAME = "authlib-injectors.json";

    private static final Set<AuthlibInjectorServer> servers = new CopyOnWriteArraySet<>();

    public static Set<AuthlibInjectorServer> getServers() {
        return servers;
    }

    private final List<String> urls;

    private AuthlibInjectorServers(List<String> urls) {
        this.urls = urls;
    }

    @Override
    public void validate() throws JsonParseException, TolerableValidationException {
        if (this.urls == null) {
            throw new JsonParseException("authlib-injectors.json -> urls cannot be null.");
        }
    }

    public static void init() {
        Path configLocation;
        Path jarPath = JarUtils.thisJarPath();
        if (jarPath != null && Files.isRegularFile(jarPath) && Files.isWritable(jarPath)) {
            configLocation = jarPath.getParent().resolve(CONFIG_FILENAME);
        } else {
            configLocation = Paths.get(CONFIG_FILENAME);
        }

        if (SettingsManager.isNewlyCreated() && Files.exists(configLocation)) {
            AuthlibInjectorServers configInstance;
            try {
                configInstance = JsonUtils.fromJsonFile(configLocation, AuthlibInjectorServers.class);
            } catch (IOException | JsonParseException e) {
                LOG.warning("Malformed authlib-injectors.json", e);

View on GitHub (pinned to 24702dc5a0)