{"record":{"id":"ef2e558c47f1df47","repo":"apache/pulsar","slug":"functions-worker-service-nar-package-name-doe","errorCode":null,"errorMessage":"Functions Worker Service Nar Package `${name}` does NOT provide a functions worker service implementation","messagePattern":"Functions Worker Service Nar Package `(.+?)` does NOT provide a functions worker service implementation","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/service/WorkerServiceLoader.java","lineNumber":85,"sourceCode":"\n    /**\n     * Load the worker service according to the worker service definition.\n     *\n     * @param metadata the worker service definition.\n     * @return\n     */\n    static WorkerServiceWithClassLoader load(WorkerServiceMetadata metadata,\n                                             String narExtractionDirectory) throws IOException {\n        final File narFile = metadata.getArchivePath().toAbsolutePath().normalize().toFile();\n        NarClassLoader ncl = NarClassLoaderBuilder.builder()\n                .narFile(narFile)\n                .parentClassLoader(WorkerService.class.getClassLoader())\n                .extractionDirectory(narExtractionDirectory)\n                .build();\n\n        WorkerServiceDefinition phDef = getWorkerServiceDefinition(ncl);\n        if (StringUtils.isBlank(phDef.getHandlerClass())) {\n            throw new IOException(\"Functions Worker Service Nar Package `\" + phDef.getName()\n                + \"` does NOT provide a functions worker service implementation\");\n        }\n\n        try {\n            Class<?> handlerClass = ncl.loadClass(phDef.getHandlerClass());\n            Object handler = handlerClass.getDeclaredConstructor().newInstance();\n            if (!(handler instanceof WorkerService)) {\n                throw new IOException(\"Class \" + phDef.getHandlerClass()\n                    + \" does not implement worker service interface\");\n            }\n            WorkerService ph = (WorkerService) handler;\n            return new WorkerServiceWithClassLoader(ph, ncl);\n        } catch (Throwable t) {\n            rethrowIOException(t);\n            return null;\n        }\n    }\n","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/service/WorkerServiceLoader.java#L67-L103","documentation":"WorkerServiceLoader.load() extracts a functions worker NAR (nar package) and reads its WorkerServiceDefinition metadata. If the definition's handlerClass is blank, the NAR does not actually provide a functions worker service implementation, so loading fails with this IOException. This prevents Pulsar from starting a worker backed by an unusable package.","triggerScenarios":"Pointing functionsWorkerServiceNarPackage at a NAR that is not a functions worker service NAR (e.g. an offset/truncate/other connector NAR, an empty or corrupted archive, or a NAR whose META-INF/services definition lacks handlerClass).","commonSituations":"Configuration mistakes swapping connector and worker NARs; building the NAR without the WorkerServiceDefinition resource; using a NAR from an incompatible Pulsar version.","solutions":["Set functionsWorkerServiceNarPackage to the correct worker service NAR (e.g. pulsar-functions/worker-something artifact), not a connector NAR","Rebuild the NAR ensuring META-INF/services contains the WorkerServiceDefinition with a non-blank handlerClass","Verify NAR integrity/version compatibility with the running Pulsar version"],"exampleFix":"// before\nfunctionsWorkerServiceNarPackage=/pulsar/connectors/pulsar-io-kafka-2.10.0.nar\n// after: use a real worker service NAR\nfunctionsWorkerServiceNarPackage=/pulsar/instances/pulsar-functions-worker-all-2.10.0.nar","handlingStrategy":"validation","validationCode":"// before starting the worker, check the NAR is a worker service package\njava.util.zip.ZipFile nar = new java.util.zip.ZipFile(narPath);\nboolean hasDef = nar.stream().anyMatch(e ->\n    e.getName().equals(\"META-INF/services/org.apache.pulsar.functions.worker.service.WorkerServiceDefinition\"));\nif (!hasDef) throw new IllegalStateException(\"Not a functions worker service NAR: \" + narPath);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never point functionsWorkerServiceNarPackage at a connector NAR","Verify NAR contents after building/publishing it","Keep the worker NAR version aligned with the Pulsar broker version","Check worker logs at startup for NAR loading errors after config changes"],"tags":["config","nar-package","startup"],"backgroundTag":"invalid-nar-package","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}