{"record":{"id":"843181fda683e766","repo":"apache/pulsar","slug":"failed-to-get-the-worker-service-definition-from","errorCode":null,"errorMessage":"Failed to get the worker service definition from ${wsNarPackage}","messagePattern":"Failed to get the worker service definition from (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/service/WorkerServiceLoader.java","lineNumber":150,"sourceCode":"     * @param wsNarPackage worker service nar package\n     * @param narExtractionDirectory the directory to extract nar directory\n     * @return the worker service\n     */\n    static WorkerService load(String wsNarPackage, String narExtractionDirectory) {\n        if (isEmpty(wsNarPackage)) {\n            return new PulsarWorkerService();\n        }\n\n        WorkerServiceDefinition definition;\n        try {\n            definition = getWorkerServiceDefinition(\n                wsNarPackage,\n                narExtractionDirectory\n            );\n        } catch (IOException ioe) {\n            log.error().attr(\"narPackage\", wsNarPackage).exception(ioe)\n                    .log(\"Failed to get the worker service definition\");\n            throw new RuntimeException(\"Failed to get the worker service definition from \"\n                + wsNarPackage, ioe);\n        }\n\n        WorkerServiceMetadata metadata = new WorkerServiceMetadata();\n        Path narPath = Paths.get(wsNarPackage);\n        metadata.setArchivePath(narPath);\n        metadata.setDefinition(definition);\n\n        WorkerServiceWithClassLoader service;\n        try {\n            service = load(metadata, narExtractionDirectory);\n        } catch (IOException e) {\n            log.error().attr(\"metadata\", metadata).exception(e)\n                    .log(\"Failed to load the worker service\");\n            throw new RuntimeException(\"Failed to load the worker service \" + metadata, e);\n        }\n\n        log.info().attr(\"metadata\", metadata)","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/service/WorkerServiceLoader.java#L132-L168","documentation":"WorkerServiceLoader.load(String wsNarPackage, String narExtractionDirectory) builds a FunctionsWorker service definition from a NAR archive. When reading the NAR's worker-service definition fails with an IOException (unreadable/corrupt archive, missing path), the loader wraps it in a RuntimeException with this message. The library throws it because it cannot proceed without a valid service definition inside the NAR package.","triggerScenarios":"Calling WorkerServiceLoader.load(narPackage, narExtractionDirectory) where narPackage does not point to a readable NAR file, the file is corrupt/truncated, or I/O fails while extracting/reading the worker service definition (the underlying IOException is attached as cause).","commonSituations":"functions_worker.yml pointing to a wrong or deleted NAR path; a partially uploaded/downloaded worker NAR; wrong file permissions; narExtractionDirectory not writable so extraction fails with IOException.","solutions":["Verify the NAR package path in functions_worker.yml (worker NarPackage setting) exists and is readable by the broker/functions worker process.","Check the wrapped IOException cause in the stack trace for the root I/O problem (corrupt jar, permission denied, no space).","Re-download/rebuild the worker NAR and verify integrity (e.g. checksum) before deployment.","Ensure narExtractionDirectory exists and is writable by the process user."],"exampleFix":"// before\nworkerConfig.setFunctionsWorkerServiceNarPackage(\"/opt/pulsar/worker.nar\"); // file does not exist\n// after\nFile nar = new File(\"/opt/pulsar/worker.nar\");\nif (!nar.isFile() || !nar.canRead()) {\n    throw new IllegalStateException(\"Worker NAR missing/unreadable: \" + nar);\n}\nworkerConfig.setFunctionsWorkerServiceNarPackage(nar.getAbsolutePath());","handlingStrategy":"validation","validationCode":"File nar = new File(wsNarPackage);\nif (!nar.isFile() || !nar.canRead() || nar.length() == 0) {\n    throw new IllegalStateException(\"Invalid worker NAR package: \" + wsNarPackage);\n}\nif (narExtractionDirectory != null && !new File(narExtractionDirectory).canWrite()) {\n    throw new IllegalStateException(\"NAR extraction dir not writable: \" + narExtractionDirectory);\n}","typeGuard":null,"tryCatchPattern":"try {\n    service = loader.load(wsNarPackage, narExtractionDirectory);\n} catch (RuntimeException e) {\n    log.error(\"Worker NAR load failed: {}\", e.getCause() != null ? e.getCause() : e);\n    throw new StartupAbortException(e);\n}","preventionTips":["Checksum-verify NAR packages at deployment time","Include NAR existence/readability checks in startup health checks","Pin the NAR path in functions_worker.yml via config management"],"tags":["pulsar-functions","nar-package","ioexception","worker-service"],"backgroundTag":"nar-archive-load-failed","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"}