{"record":{"id":"abeaf45bcfbbebb3","repo":"apache/pulsar","slug":"failed-to-load-the-worker-service-metadata","errorCode":null,"errorMessage":"Failed to load the worker service ${metadata}","messagePattern":"Failed to load the worker service (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/service/WorkerServiceLoader.java","lineNumber":165,"sourceCode":"        } 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)\n                .log(\"Successfully loaded worker service\");\n        return service;\n    }\n}\n","sourceCodeStart":147,"sourceCodeEnd":173,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/service/WorkerServiceLoader.java#L147-L173","documentation":"This is the public entry point WorkerServiceLoader.load(metadata, narExtractionDirectory) that delegates to the internal load and rethrows any IOException as a RuntimeException('Failed to load the worker service ' + metadata). It indicates the worker service could not be loaded from the NAR described by the WorkerServiceMetadata (archive path, definition), with the underlying IOException as cause.","triggerScenarios":"Calling WorkerServiceLoader.load(WorkerConfig, ...) / load(metadata, narExtractionDirectory) when the internal load throws IOException: NAR missing, unreadable, corrupt, or extraction to narExtractionDirectory fails.","commonSituations":"Broker startup with a misconfigured worker service NAR; NAR deleted between metadata creation and load; read/extract permission issues; wrong narExtractionDirectory.","solutions":["Inspect the cause IOException in the stack trace to identify the actual file/IO failure.","Confirm metadata.getArchivePath() exists and is a valid NAR archive readable by the process.","Fix the functions_worker.yml NAR package configuration and restart the functions worker.","Verify narExtractionDirectory permissions and disk space."],"exampleFix":"// before\n// functions_worker.yml: functionsWorkerServiceNarPackage: /opt/pulsar/workersvc.nar (file missing)\n// after\n// ensure file exists and path is correct:\n// ls -l /opt/pulsar/workersvc.nar && chmod a+r /opt/pulsar/workersvc.nar\n// then restart the functions worker","handlingStrategy":"try-catch","validationCode":"WorkerServiceMetadata md = /* built metadata */;\nFile archive = md.getArchivePath().toFile();\nif (archive == null || !archive.isFile() || !archive.canRead()) {\n    throw new IllegalStateException(\"Worker service archive missing: \" + md);\n}","typeGuard":null,"tryCatchPattern":"try {\n    WorkerServiceWithClassLoader svc = WorkerServiceLoader.load(config, narExtractionDirectory);\n} catch (RuntimeException e) {\n    log.error(\"Failed to load worker service: {}\", e.getCause(), e);\n    throw e; // fail fast at startup\n}","preventionTips":["Log and inspect the cause IOException, not just the wrapper","Keep NAR extraction directory on a writable volume with free space","Test worker NAR loading in CI before deploying"],"tags":["pulsar-functions","nar-package","worker-service","ioexception"],"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-14T00:17:10.932Z"}