{"record":{"id":"a72747cd09321712","repo":"apache/pulsar","slug":"loading-failed-due-to","errorCode":null,"errorMessage":"Loading '' failed due to ","messagePattern":"Loading '' failed due to ","errorType":"exception","errorClass":"UncheckedIOException","httpStatus":null,"severity":"error","filePath":"pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/FunctionFilePackage.java","lineNumber":82,"sourceCode":"            try {\n                classpathFromArchive = NarClassLoader.getClasspathFromArchive(file, narExtractionDirectory);\n            } catch (IOException e) {\n                throw new UncheckedIOException(e);\n            }\n            List<ClassFileLocator> classFileLocators = new ArrayList<>();\n            classFileLocators.add(ClassFileLocator.ForClassLoader.ofSystemLoader());\n            for (File classpath : classpathFromArchive) {\n                if (classpath.exists()) {\n                    try {\n                        ClassFileLocator locator;\n                        if (classpath.isDirectory()) {\n                            locator = new ClassFileLocator.ForFolder(classpath);\n                        } else {\n                            locator = ClassFileLocator.ForJarFile.of(classpath);\n                        }\n                        classFileLocators.add(locator);\n                    } catch (IOException e) {\n                        throw new UncheckedIOException(\"Loading '\" + classpath + \"' failed due to \" + e.getMessage(),\n                                e);\n                    }\n                }\n            }\n            this.classFileLocator = new ClassFileLocator.Compound(classFileLocators);\n            this.typePool = TypePool.Default.of(classFileLocator);\n            try {\n                this.configMetadata = FunctionUtils.getPulsarIOServiceConfig(file, configClass);\n            } catch (IOException e) {\n                throw new UncheckedIOException(e);\n            }\n        } else {\n            try {\n                this.classFileLocator = nonZeroFile\n                        ? new ClassFileLocator.Compound(ClassFileLocator.ForClassLoader.ofSystemLoader(),\n                                ClassFileLocator.ForJarFile.of(file)) :\n                        new ClassFileLocator.Compound(ClassFileLocator.ForClassLoader.ofSystemLoader());\n            } catch (IOException e) {","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/FunctionFilePackage.java#L64-L100","documentation":"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>\".","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the path in the message: verify the file/jar exists and is readable by the worker process.","Re-upload/re-download the package if the archive is truncated or corrupt.","Fix filesystem permissions or mount issues on the worker.","Ensure the path is a real jar or directory (not a symlink target that is missing)."],"exampleFix":"// before\nnew FunctionFilePackage(\"/uploads/func.jar\", ...); // jar was deleted\n// after\nif (java.nio.file.Files.isReadable(java.nio.file.Path.of(\"/uploads/func.jar\"))) {\n    new FunctionFilePackage(\"/uploads/func.jar\", ...);\n}","handlingStrategy":"try-catch","validationCode":"java.nio.file.Path p = java.nio.file.Path.of(classpathEntry);\nif (!java.nio.file.Files.isRegularFile(p) && !java.nio.file.Files.isDirectory(p)) {\n    throw new IllegalStateException(\"Missing classpath entry: \" + classpathEntry);\n}\nif (!java.nio.file.Files.isReadable(p)) {\n    throw new IllegalStateException(\"Not readable: \" + classpathEntry);\n}","typeGuard":"static boolean isUsableClasspathEntry(String path) {\n    if (path == null) return false;\n    java.nio.file.Path p = java.nio.file.Path.of(path);\n    return (java.nio.file.Files.isRegularFile(p) || java.nio.file.Files.isDirectory(p))\n        && java.nio.file.Files.isReadable(p);\n}","tryCatchPattern":"try {\n    new FunctionFilePackage(classpath, ...);\n} catch (UncheckedIOException e) {\n    log.error(\"Package load failed for {}: {}\", classpath, e.getCause().getMessage());\n    // re-upload or fix the archive before retrying\n}","preventionTips":["Verify every classpath entry exists and is readable before constructing.","Validate jar integrity (size/checksum) after upload.","Watch worker filesystem permissions and disk-full conditions.","Avoid moving/deleting package files while workers may load them."],"tags":["pulsar-functions","classpath","io","file-not-found"],"backgroundTag":"classpath-load-failure","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}