apache/pulsar · critical · RuntimeException

Failed to get the worker service definition from ${wsNarPack

Error message

Failed to get the worker service definition from ${wsNarPackage}

What it means

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.

Source

Thrown at pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/service/WorkerServiceLoader.java:150

     * @param wsNarPackage worker service nar package
     * @param narExtractionDirectory the directory to extract nar directory
     * @return the worker service
     */
    static WorkerService load(String wsNarPackage, String narExtractionDirectory) {
        if (isEmpty(wsNarPackage)) {
            return new PulsarWorkerService();
        }

        WorkerServiceDefinition definition;
        try {
            definition = getWorkerServiceDefinition(
                wsNarPackage,
                narExtractionDirectory
            );
        } catch (IOException ioe) {
            log.error().attr("narPackage", wsNarPackage).exception(ioe)
                    .log("Failed to get the worker service definition");
            throw new RuntimeException("Failed to get the worker service definition from "
                + wsNarPackage, ioe);
        }

        WorkerServiceMetadata metadata = new WorkerServiceMetadata();
        Path narPath = Paths.get(wsNarPackage);
        metadata.setArchivePath(narPath);
        metadata.setDefinition(definition);

        WorkerServiceWithClassLoader service;
        try {
            service = load(metadata, narExtractionDirectory);
        } catch (IOException e) {
            log.error().attr("metadata", metadata).exception(e)
                    .log("Failed to load the worker service");
            throw new RuntimeException("Failed to load the worker service " + metadata, e);
        }

        log.info().attr("metadata", metadata)

View on GitHub (pinned to 820761864e)

Solutions

1. Verify the NAR package path in functions_worker.yml (worker NarPackage setting) exists and is readable by the broker/functions worker process.
2. Check the wrapped IOException cause in the stack trace for the root I/O problem (corrupt jar, permission denied, no space).
3. Re-download/rebuild the worker NAR and verify integrity (e.g. checksum) before deployment.
4. Ensure narExtractionDirectory exists and is writable by the process user.

Example fix

// before
workerConfig.setFunctionsWorkerServiceNarPackage("/opt/pulsar/worker.nar"); // file does not exist
// after
File nar = new File("/opt/pulsar/worker.nar");
if (!nar.isFile() || !nar.canRead()) {
    throw new IllegalStateException("Worker NAR missing/unreadable: " + nar);
}
workerConfig.setFunctionsWorkerServiceNarPackage(nar.getAbsolutePath());

File nar = new File(wsNarPackage);
if (!nar.isFile() || !nar.canRead() || nar.length() == 0) {
    throw new IllegalStateException("Invalid worker NAR package: " + wsNarPackage);
}
if (narExtractionDirectory != null && !new File(narExtractionDirectory).canWrite()) {
    throw new IllegalStateException("NAR extraction dir not writable: " + narExtractionDirectory);
}

try {
    service = loader.load(wsNarPackage, narExtractionDirectory);
} catch (RuntimeException e) {
    log.error("Worker NAR load failed: {}", e.getCause() != null ? e.getCause() : e);
    throw new StartupAbortException(e);
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Failed to load the worker service ${metadata}
• RuntimeException(conversionError)
• Failed to get schema ledger for${key}
• Failed to read token from file
• You must specify either a Fully Qualified Function Name (FQF

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