apache/pulsar · error · UncheckedIOException

Loading '' failed due to

Error message

Loading '' failed due to 

What it means

FunctionFilePackage scans each classpath entry (a folder or jar) to build a ByteBuddy ClassFileLocator. If opening/reading an entry throws IOException, it is rethrown as UncheckedIOException with message "Loading '<path>' failed due to <reason>".

Source

Thrown at pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/FunctionFilePackage.java:82

            try {
                classpathFromArchive = NarClassLoader.getClasspathFromArchive(file, narExtractionDirectory);
            } catch (IOException e) {
                throw new UncheckedIOException(e);
            }
            List<ClassFileLocator> classFileLocators = new ArrayList<>();
            classFileLocators.add(ClassFileLocator.ForClassLoader.ofSystemLoader());
            for (File classpath : classpathFromArchive) {
                if (classpath.exists()) {
                    try {
                        ClassFileLocator locator;
                        if (classpath.isDirectory()) {
                            locator = new ClassFileLocator.ForFolder(classpath);
                        } else {
                            locator = ClassFileLocator.ForJarFile.of(classpath);
                        }
                        classFileLocators.add(locator);
                    } catch (IOException e) {
                        throw new UncheckedIOException("Loading '" + classpath + "' failed due to " + e.getMessage(),
                                e);
                    }
                }
            }
            this.classFileLocator = new ClassFileLocator.Compound(classFileLocators);
            this.typePool = TypePool.Default.of(classFileLocator);
            try {
                this.configMetadata = FunctionUtils.getPulsarIOServiceConfig(file, configClass);
            } catch (IOException e) {
                throw new UncheckedIOException(e);
            }
        } else {
            try {
                this.classFileLocator = nonZeroFile
                        ? new ClassFileLocator.Compound(ClassFileLocator.ForClassLoader.ofSystemLoader(),
                                ClassFileLocator.ForJarFile.of(file)) :
                        new ClassFileLocator.Compound(ClassFileLocator.ForClassLoader.ofSystemLoader());
            } catch (IOException e) {

View on GitHub (pinned to 820761864e)

Solutions

1. Check the path in the message: verify the file/jar exists and is readable by the worker process.
2. Re-upload/re-download the package if the archive is truncated or corrupt.
3. Fix filesystem permissions or mount issues on the worker.
4. Ensure the path is a real jar or directory (not a symlink target that is missing).

Example fix

// before
new FunctionFilePackage("/uploads/func.jar", ...); // jar was deleted
// after
if (java.nio.file.Files.isReadable(java.nio.file.Path.of("/uploads/func.jar"))) {
    new FunctionFilePackage("/uploads/func.jar", ...);
}

java.nio.file.Path p = java.nio.file.Path.of(classpathEntry);
if (!java.nio.file.Files.isRegularFile(p) && !java.nio.file.Files.isDirectory(p)) {
    throw new IllegalStateException("Missing classpath entry: " + classpathEntry);
}
if (!java.nio.file.Files.isReadable(p)) {
    throw new IllegalStateException("Not readable: " + classpathEntry);
}

static boolean isUsableClasspathEntry(String path) {
    if (path == null) return false;
    java.nio.file.Path p = java.nio.file.Path.of(path);
    return (java.nio.file.Files.isRegularFile(p) || java.nio.file.Files.isDirectory(p))
        && java.nio.file.Files.isReadable(p);
}

try {
    new FunctionFilePackage(classpath, ...);
} catch (UncheckedIOException e) {
    log.error("Package load failed for {}: {}", classpath, e.getCause().getMessage());
    // re-upload or fix the archive before retrying
}

When it happens

Trigger: Constructing FunctionFilePackage with a classpath entry pointing to a non-existent, unreadable, or corrupt file/jar, or a directory path that cannot be opened as a folder locator.

Common situations: Package file moved/deleted between upload and processing; wrong path in worker config; truncated or corrupted jar from a failed upload; permission issues on the worker filesystem.

Related errors

• Cannnot get absolute path from specified URL
• Config class not found: %s
• Timestamp extractor class %s must be in class path
• Log folder creation error
• does not exists locally

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/a72747cd09321712. Report an issue: GitHub.