openjdk/jdk · warning

WARNING: unable to canonicalize %s\n

Error message

WARNING: unable to canonicalize %s\n

What it means

Warning from Boot-Class-Path processing for a relative entry: JDK_Canonicalize failed on the agent jar's own path, so the relative boot path cannot be resolved against the jar's parent directory and the entry is skipped. Startup continues without this bootstrap search entry.

Source

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

        /*
         * If the path is an absolute path then add to the bootclassloader
         * search path. Otherwise we get the canonical path of the agent jar
         * and then use its base path (directory) to resolve the given path
         * segment.
         *
         * NOTE: JVMTI is specified to use modified UTF8 strings (like JNI).
         * In 1.5.0 the AddToBootstrapClassLoaderSearch takes a platform string
         * - see 5049313.
         */
        if (isAbsolute(path)) {
            jvmtierr = (*jvmtienv)->AddToBootstrapClassLoaderSearch(jvmtienv, path);
        } else {
            char* resolved;

            if (!haveBasePath) {
                if (JDK_Canonicalize((char*)jarfile, canonicalPath, sizeof(canonicalPath)) != 0) {
                    fprintf(stderr, "WARNING: unable to canonicalize %s\n", jarfile);
                    free(path);
                    continue;
                }
                parent = basePath(canonicalPath);
                jplis_assert(parent != (char*)NULL);
                haveBasePath = 1;
            }

            resolved = resolve(parent, path);
            jvmtierr = (*jvmtienv)->AddToBootstrapClassLoaderSearch(jvmtienv, resolved);
            free(resolved);
        }

        /* print warning if boot class path not updated */
        if (jvmtierr != JVMTI_ERROR_NONE) {
            check_phase_blob_ret(jvmtierr, free(path));

            fprintf(stderr, "WARNING: %s not added to bootstrap class loader search: ", path);

View on GitHub (pinned to 88dfb74bbe)

Solutions

1. Copy the agent jar to a stable, readable local directory before loading it
2. Use absolute paths in Boot-Class-Path so no canonicalization of the jar location is needed
3. Ensure the JVM user has read/traverse permissions on every component of the jar path

Example fix

# before
Boot-Class-Path: lib/extra-boot.jar  # relative, needs canonicalize
# after
Boot-Class-Path: /opt/agent/lib/extra-boot.jar  # absolute

// pre-canonicalize at deploy time and verify readability
Path p = Path.of(agentPath).toRealPath(); // throws if unresolvable
if (!Files.isReadable(p)) throw new IllegalStateException("agent jar unreadable: " + p);

When it happens

Trigger: The agent jar path itself cannot be canonicalized — deleted or renamed jar between load and canonicalization, permission problems reading the directory, or a path exceeding platform limits.

Common situations: Attaching to a jar that a cleanup process deletes mid-attach; agents loaded from ephemeral temp directories; network-mounted filesystems with canonicalization failures.

Related errors

• WARNING: illegal character in Boot-Class-Path value: %s\n
• WARNING: %s not added to bootstrap class loader search:
• JVMTI_ERROR_ILLEGAL_ARGUMENT
• Unexpected error: %d\n
• AGENT_ERROR_NOTONCP

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