WARNING: illegal character in Boot-Class-Path value: %s\n

Error message

WARNING: illegal character in Boot-Class-Path value: %s\n

What it means

Warning emitted while expanding the Boot-Class-Path manifest attribute of an agent jar: the path component contains characters that are not legal in a URI path (per PathCharsValidator), so the entry is skipped and that path is not added to the bootstrap class loader search. Agent startup continues; only that classpath entry is lost.

Source

Thrown at src/java.instrument/share/native/libinstrument/InvocationAdapter.c:890

         */
        path = strdup(paths[i]);
        jplis_assert(path != (char*)NULL);

        /*
         * The attribute is specified to be a list of relative URIs so in theory
         * there could be a query component - if so, get rid of it.
         */
        pos = strchr(path, '?');
        if (pos != NULL) {
            *pos = '\0';
        }

        /*
         * Check for characters that are not allowed in the path component of
         * a URI.
         */
        if (validatePathChars(path)) {
            fprintf(stderr, "WARNING: illegal character in Boot-Class-Path value: %s\n",
               path);
            free(path);
            continue;
        }


        /*
         * Next decode any escaped characters. The result is a UTF8 string.
         */
        TRANSFORM(path, decodePath(path,&len));

        /*
         * Convert to the platform encoding
         */
        {
            char platform[MAXPATHLEN];
            int new_len = convertUtf8ToPlatformString(path, len, platform, MAXPATHLEN);
            free(path);

View on GitHub (pinned to 88dfb74bbe)

Solutions

Percent-encode illegal characters in Boot-Class-Path entries (e.g. %20 for space) or remove the offending characters
Move the referenced jar/dir to a path without spaces or special characters
Re-check with -verbose:class or -Xlog:class+load which classes came from the boot path to confirm the fix

Example fix

# before (manifest)
Boot-Class-Path: /opt/my libs/agent-boot.jar
# after
Boot-Class-Path: /opt/my%20libs/agent-boot.jar

Defensive patterns

Strategy: validation

Validate before calling

// lint Boot-Class-Path entries at build time
for (String e : bootClassPath.split(" ")) {
    String path = e.split("[?]")[0];
    if (!path.matches("[A-Za-z0-9:/_.%~-]+"))
        throw new IllegalArgumentException("Boot-Class-Path entry has illegal chars: " + e);
}

Prevention

Percent-encode spaces and special characters in manifest paths
Prefer deployment directories without spaces for agents and their boot jars

When it happens

Trigger: A Boot-Class-Path entry containing characters like space, '[' or non-URI-safe bytes that are not percent-encoded; entries with unescaped non-ASCII on some platforms.

Common situations: Agent jars built on Windows with 'C:\Program Files\...' paths in Boot-Class-Path; manifests containing raw spaces in directory names.

Related errors

AI-assisted analysis of openjdk/jdk@88dfb74bbe (2026-08-14). Data as JSON: /api/errors/5027676bbb922e6c. Report an issue: GitHub.